Traces

Tracing gives you end-to-end visibility into the life of a request as it travels through your Workers application and connected services, helping you to identify performance bottlenecks, debug issues, and understand complex request flows.

With tracing you can answer questions such as:

• What is the cause of a long-running request?
• Where in the chain of services did a request fail?
• How long do subrequests to my Worker take?
• How long are my requests to my KV Namespace or R2 bucket taking?

Automatic instrumentation

Each trace consists of one or more spans, representing the various calls made to different Worker services as part of the invocation. Cloudflare has automatically instrumented fetch calls and requests to Cloudflare resources (e.g. Workers KV, D1 Databases, Durable Objects) bound to your Workers application, without requiring you to install and configure an OpenTelemetry SDK.

Take for example, application that handles online ordering and makes request to a D1 Database to fetch customer information, an external API to validate payment information, and a Cloudflare Queue to submit the order.

Tracing lets you visualize an invocation call by call at each part of the request journey. Our example above may look something like this:

TODO: insert example of trace here

How to enable tracing

If you would like to view traces in the Cloudflare Dashboard using Workers Observability, you can set the following in your Wrangler configuration file:

wrangler.jsonc

{
  "observability": {
    // enabling traces
    "traces": {
      "enabled": true,
    },
  }
}

You can also export OpenTelemetry traces to a 3rd party destination such as Datadog or Honeycomb.

Exporting OpenTelemetry traces to a 3rd party destination

In addition to viewing traces in the Cloudflare Dashboard, you can export traces to any OpenTelemetry-compatible destination, including popular platforms such as Datadog and Honeycomb.

To configure trace export to external destinations, you'll need to set up a destination in the Cloudflare dashboard and set your desired destination within your Wrangler configuration.

Head-based sampling

Head-based sampling allows you to trace a percentage of incoming requests in your Cloudflare Worker. Most production applications at scale use head sampling because it is unnecessary and costly to trace every single request. With sampling, you can help reduce volume and manage costs, while still providing meaningful insights into your application.

You can configure head-based sampling for both tracing and logging separately on a per-Worker basis. The valid range is from 0 to 1, where 0 indicates zero out of one hundred invocations will be traced, and 1 indicates every requests will be traced. If head_sampling_rate is unspecified, it defaults to tracing 100% of requests.

You can configure this in your Wrangler configuration like this:

wrangler.jsonc

{
    "tracing": {
        //enables tracing (required field)
        "enabled": true
        "destinations": ["external", "cloudflare"]
        // set tracing sampling rate to 5%
        "head_sample_rate": 0.05
    },
    // optional override since {obs enabled:true}
    "logging": {
        "enabled": true
        // set logging sampling rate to 50%
        "head_sample_rate": 0.5
    }
}

Limits & Pricing

Workers tracing is currently free during the early beta period. This includes all tracing functionality: collecting traces, storing them, and viewing them in the Cloudflare dashboard.

Starting on xx/xx/xxxx, tracing will be billed as part of Workers observability. Each span in a trace counts as one observability event, sharing the same monthly quota and pricing as Workers logs ↗:

	Events (trace spans or log events)	Retention
Workers Free	100,000 per day	3 Days
Workers Paid	10 million included per month +$0.05 per additional 100,000 events	30 Days

When billing begins on xx/xx/xxxx, you'll automatically start being charged based on your plan.

Spans and attributes

While our work for automatic instrumentation is ongoing, we've documented all existing spans and attributes currently instrumented today.

• Spans and attributes