Cloudflare Trace: Making Ruleset Behavior Visible
Cloudflare has released Cloudflare Trace, a diagnostic tool available to all customers that shows how HTTP requests move through a zone's configuration. The feature reveals which Cloudflare Rules are applied to a given request, addressing what has long been a visibility gap: the sequence of products, each potentially modifying traffic, that a request encounters between a client and an origin.
The problem is compounded in accounts with multiple administrators. When different people manage different rules, predicting how a request will be handled becomes difficult, as a rule added by one admin may interact unexpectedly with rules from another. Cloudflare Trace is designed to remove that guesswork.
Running a trace
To run a trace, a user specifies a URL that is proxied through Cloudflare and an HTTP method such as GET. Optional parameters include request headers, a request body, and a bot score, which allows testing how security rules behave under different conditions.
The dashboard then shows a visualization of the products that matched the request — for example, Configuration Rules, Transform Rules, and Firewall Rules — along with the specific rules inside each phase that were applied. Clicking a rule ID opens that rule in the Cloudflare Dashboard for editing. The interface also generates a command-line version of the trace, so customers can script traces and pipe the JSON output into tools like jq for deeper inspection.
The lifecycle of a request, from diagram to tool
Cloudflare's own engineers have long struggled to document the request lifecycle. An internal wiki page, "Life of a Request Museum," archives diagram attempts from engineers, product heads, and marketing over the past 13 years. The challenge is that Cloudflare's product set changes quickly; a diagram drawn weeks ago can be obsolete. The markering diagram below, used in 2018, shows how quickly such visuals age.
Earlier attempts at transparency, such as the Traffic Sequence dashboard feature, gave a high-level view of product ordering but lacked fine detail. Internally, Cloudflare teams use a more verbose tool called Flute, which outputs every rule, feature, and code path a request takes. The image below illustrates a Flute trace evaluating a request against Single Redirects, Waiting Room, Configuration Settings, Snippets, and Origin Rules.
Flute, however, was too intricate to expose to customers directly. Its output can create more questions than answers. To find the right level of detail for Cloudflare Trace, the team collaborated with Cloudflare Support to understand the most common customer issues, which generally centered on which rules applied to specific requests. Support teams frequently had to escalate such inquiries for investigation.
Cloudflare Trace shifts that investigative burden to the customer, reducing support load in the process. When customers do encounter genuine issues, they can export the JSON response of a trace and attach it to a support ticket, shortening resolution time significantly.
Real-world debugging examples
Cloudflare Trace has been available via API for nine months, and the team has used that period to work with customers on practical problems. Two examples illustrate the tool's value.
Inconsistent Transform Rule matches
A customer using Transform Rules to rewrite URLs for specific paths found that a small percentage of requests were sent to the origin untransformed, causing application errors. A systems administrator compared traces of a working request against a failing one. In the problematic trace, only one rule matched and set incorrect parameters; in the working trace, the regex-based rule matched as intended.
The traces revealed that the regex was written to handle subdirectory paths but not requests for a root or non-subdirectory path. Once the filter was updated to cover both cases, all requests matched as expected.
Multiple origin rules, unexpected routing
Within a phase such as Origin Rules, all matching rules are applied in priority order. That means rule 1 may set a Host Header while rule 3 assigns a different DNS origin, causing the request to exit the phase with a new Host Header but be routed elsewhere. Cloudflare Trace surfaces every matched rule in the phase, making it easy to see how the combination of rules produced the final request behavior.
Availability and roadmap
Cloudflare Trace is rolling out to all customers over the coming week, located in the Account section of the Cloudflare Dashboard and available on all plans. Future development will add scheduling and alerts, allowing customers to monitor whether a newly deployed rule affects critical request paths. Feedback is collected via a form within the Trace dashboard to guide the product before its general release.
