Cloudflare Traces Tutorial: Trace Web Requests End to End

Cloudflare Traces entered open beta on October 2, 2026, giving developers a request-level view of what happens between a visitor and an origin server. Instead of piecing together cache logs, routing rules, Worker activity, and origin timings, you can inspect supported parts of that path as one trace. This tutorial explains how the new tracing model works, how to enable it, how sampling and Trace Rules fit together, and where the new pricing changes matter.

Cloudflare Traces follows the request instead of just the application

A traditional application trace usually starts after a request reaches your application. Cloudflare Traces moves that boundary outward: the trace can include supported security rules, transformations, cache decisions, routing, Worker execution, and the connection to your origin. Each part is represented as a span, which is a timed record describing one operation inside a larger request. That makes the tool useful when the application itself looks healthy but the request is slow or changed somewhere before it reaches your code.

This distinction matters because Cloudflare Trace and Cloudflare Traces solve different debugging problems. The older Trace feature simulates a request and shows which configured rules would execute, while Cloudflare Traces records the path of actual requests through supported parts of the platform. One answers “what would happen?” and the other helps answer “what happened?”

Enable Cloudflare Traces for the domain you want to investigate

Cloudflare says Cloudflare Traces can be enabled from the dashboard for a domain, and the initial open beta does not require you to add tracing instrumentation to your application. Once tracing is enabled, Cloudflare can automatically generate spans for supported operations. That is particularly useful for teams that already have a production application behind Cloudflare but do not want to retrofit tracing code into every service before investigating a problem.

The important setup decision is the sampling rate. Sampling determines what proportion of incoming requests receives tracing data. For example, a 1% rate means that tracing is attempted for roughly one request out of every 100, while a 100% rate captures every request selected by the tracing configuration. Cloudflare recommends using sampling to balance visibility against data volume, especially when a site receives substantial traffic.

{ "observability": { "traces": { "enabled": true, "head_sampling_rate": 0.05 } } }

For Workers, the same concept can be configured through Wrangler with observability.traces.enabled and head_sampling_rate. Cloudflare's Workers documentation says the default sampling rate is 1, meaning 100% of requests are traced when tracing is enabled, while a value such as 0.05 represents 5%.

Use Trace Rules when a low sampling rate is not enough

A low baseline rate is useful for continuous visibility, but it creates an obvious problem during an incident: the particular failing request may not be sampled. Cloudflare Traces addresses that with Trace Rules, which let you override the baseline for traffic matching conditions such as a hostname, path, IP address, header, method, or geography. You can therefore keep normal traffic at a low rate while collecting much more detailed data for a specific investigation.

Consider a production API where one customer reports intermittent latency. Tracing every request would create unnecessary telemetry, but tracing only 1% could miss the customer's request. A Trace Rule can target an identifying request property and temporarily capture that traffic at a higher rate. The practical advantage is not simply more data; it is being able to collect the right data without turning tracing into an always-on firehose.

Read the trace as a timeline of what the request actually did

Once a trace is available, start at the request and follow the nested spans rather than jumping directly to the longest number. Cloudflare's examples show spans for security evaluation, URL transformations, Worker routing, cache behavior, upstream connections, and origin handling. Each span provides timing and other attributes that help explain where the request spent its time.

Suppose a request takes 539 milliseconds and the trace shows a cache miss followed by 527 milliseconds spent getting the response from the origin. The useful conclusion is not simply that the request was “slow.” The trace points toward the origin path as the dominant part of that particular request, while the cache miss explains why the request did not finish from cached content. That is much more actionable than a single total-duration metric.

Cloudflare Traces can connect with application traces through OpenTelemetry

The more interesting part for developers running multiple services is trace context propagation. Cloudflare Traces can accept a W3C traceparent header, allowing Cloudflare spans to join an existing distributed trace, and it can forward trace context toward an origin. If the services behind that origin also produce compatible telemetry, the Cloudflare and application spans can be viewed as one connected trace in an OpenTelemetry-compatible backend.

OpenTelemetry, often shortened to OTel, is a vendor-neutral framework for generating, collecting, and exporting telemetry such as traces, metrics, and logs. Cloudflare's export support uses the OpenTelemetry Protocol, or OTLP, so traces can be sent to compatible observability systems instead of remaining only in the Cloudflare dashboard.

That creates a useful debugging chain: a request enters through Cloudflare, passes through the platform, reaches your application, calls another service, and returns a response. Without distributed context, those systems may each show a separate timing record. With trace context, the records can be connected so you can see how the individual pieces contributed to one request.

Workers developers can add their own spans when automatic tracing stops short

Automatic instrumentation covers many Worker operations, including outbound fetches and interactions with supported bindings such as KV, R2, and Durable Objects. If you need visibility into application-specific work, Workers also supports custom spans. A custom span is a developer-created timing boundary around code that Cloudflare cannot automatically understand as a distinct operation.

import { tracing } from "cloudflare:workers";

export default {
async fetch(request, env, ctx) {
return tracing.enterSpan("handleRequest", async (span) => {
span.setAttribute(
"url.path",
new URL(request.url).pathname
);

 return buildResponse();
});

}
};

The enterSpan() method creates a span that automatically ends when its callback finishes. That makes it suitable for wrapping a meaningful section of application logic without manually starting and stopping a timer. Cloudflare also provides startActiveSpan() and startSpan() for cases where the lifetime of the operation needs more control. Cloudflare Docs

OpenTelemetry export keeps the trace usable outside Cloudflare

Cloudflare supports exporting Cloudflare Traces and Workers telemetry to external destinations that accept OTLP. Its current documentation lists destinations and configuration options for services including Honeycomb, Grafana Cloud, Splunk, and SigNoz. The dashboard lets you create an account-level destination and then associate it with the relevant telemetry source. Cloudflare Docs

Workers can also export traces directly through Wrangler configuration. The destinations setting identifies the configured destination, while persist controls whether Cloudflare keeps a copy of the exported telemetry. Setting persist to false is useful when an external observability platform is intended to be the only trace destination. Cloudflare Docs

The December pricing change makes sampling a practical concern

Cloudflare Traces is launching under a pricing transition that developers should understand before enabling high-volume tracing. Cloudflare says its unified Observability pricing will take effect on December 1, 2026, with Free plans receiving 0.5 GB of observability ingestion per day and Paid and Enterprise plans receiving 50 GB of ingestion plus 10 GB-month of storage per billing cycle. Additional ingestion is listed at $0.25 per GB and additional storage at $0.10 per GB-month for the Paid and Enterprise model described by Cloudflare. Cloudflare Docs +1

That changes the practical meaning of a 100% sampling rate. It is not automatically wrong, but a busy application can generate substantially more telemetry when every request is traced. A lower baseline combined with targeted Trace Rules gives developers a way to retain continuous visibility while concentrating detailed traces on the traffic they actually need to investigate. Cloudflare Blog

What Cloudflare Traces does not cover yet

The open beta is not the final tracing system. Cloudflare says broader automatic instrumentation is planned for additional HTTP request and Workers execution stages, along with authenticated trace-context propagation, ad hoc tracing, OpenTelemetry API support in Workers, and longer retention. The current system therefore provides a much wider request view than Workers-only tracing, but its coverage is still explicitly expanding. Cloudflare Blog

There is also a separate distinction for Workers telemetry. Workers tracing already provides automatic instrumentation for operations inside the Workers environment, while Cloudflare Traces extends tracing outward to supported parts of the broader request path. Developers working on Workers should therefore treat these as related layers rather than assuming that enabling one automatically provides every span from the browser-facing request through every backend service. Cloudflare Docs +1

Start with a small sampling rate and trace the problem traffic

For a production application, the sensible starting point is to enable tracing, choose a modest baseline sampling rate, and then create targeted Trace Rules when an investigation requires more detail. Use the dashboard timeline to determine whether time is being spent in Cloudflare processing, cache behavior, the Worker, the origin, or another connected service. If your existing observability stack already supports OpenTelemetry, exporting the traces lets you correlate Cloudflare's view with application telemetry instead of maintaining two unrelated debugging timelines. Cloudflare Blog +1

The useful shift is that a slow web request no longer has to be treated as an unexplained number at the edge. Cloudflare Traces gives developers a way to follow that request through the infrastructure in between, while sampling and trace rules provide control over how much of that visibility is collected. As the beta adds more instrumentation, the key question will be how much of the full request path can be represented in one trace without turning observability into another source of operational cost.