--- a/mod_firewall/README.md	Mon May 11 13:18:45 2026 +0100
+++ b/mod_firewall/README.md	Mon May 11 13:37:19 2026 +0100
@@ -842,3 +842,73 @@
 Example to limit stanzas per session type:
 
     LIMIT: normal on $(session.type)
+
+### Tracing
+
+mod_firewall has tracing functionality, to help with debugging scripts and
+rules.
+
+To enable tracing for a script, add at the top:
+
+```
+@@ trace = on
+```
+
+All chains defined in the script will then have tracing activated. Note that
+this has a small performance impact (in processing and in memory allocations),
+even when the tracing functionality is not actively being used.
+
+You need to reload mod_firewall after enabling tracing in a script, so it will
+pick up the change and recompile the rules.
+
+When tracing is enabled, you can trace all evaluations by running:
+
+```
+prosodyctl shell firewall trace HOST
+```
+
+Replace HOST with the name of the host/component you want to trace (obviously
+mod_firewall must be loaded on that host).
+
+What is a trace? When tracing is enabled, a trace is generated each time a
+chain runs an evaluation of a stanza. The trace records the script name, chain
+name, the stanza that was being evaluated, and which rules/conditions matched.
+This information is then sent to any active 'trace' commands. If no commands
+are active, traces are discarded.
+
+Note that traces are per-chain and only printed when they are complete. This
+can result in unintuitive ordering of the output when multiple chains are
+invoked during processing of a stanza. Results of traces from "inner" chains
+will be displayed before traces from an "outer" chain.
+
+#### Tagging traces
+
+Sometimes you only need to trace a subset of evaluations. To do this, you can
+use the `TAG TRACE` action. This will apply a tag to the trace of the current
+evaluation.
+
+For example, if you only want to trace stanzas sent to a specific JID:
+
+```
+TO: user@example.com
+TAG TRACE=interesting
+```
+
+Then you can filter for this tag when you watch traces:
+
+```
+prosodyctl shell firewall trace --tag=interesting HOST
+```
+
+You can filter by the special tag name `untagged` to only show traces which
+have not been tagged.
+
+Notes on trace tagging:
+
+- Traces are per chain, however tags will propagate through to future chains
+  which execute on the same event. This allows easily tracing a stanza through
+  multiple chains, for example.
+- A trace may only have one tag. If `TAG TRACE` is used multiple times, it
+  will overwrite the tag for the current trace and any future chains which run
+  on this event/stanza. Chains (other than the current one) which already
+  began evaluation won't use the new tag.