Custom spans now available in Workers tracing

You can now create custom trace spans in your Workers code using tracing.enterSpan(). Custom spans appear alongside the automatic platform instrumentation (fetch calls, KV reads, D1 queries, and other platform operations) in your traces and OpenTelemetry exports, with correct parent-child nesting.

The API is available via import { tracing } from "cloudflare:workers" or through the handler context as ctx.tracing:

<div><div><span>import </span><span>{</span><span><span> </span><span>tracing</span><span> </span></span><span>}</span><span> from </span><span>"cloudflare:workers"</span><span>;</span></div></div><div><div>
</div></div><div><div><span>export</span><span> </span><span>default</span><span> </span><span>{</span></div></div><div><div><span>  </span><span>async</span><span> </span><span>fetch</span><span>(</span><span>request</span><span>,</span><span> </span><span>env</span><span>,</span><span> </span><span>ctx</span><span>)</span><span> </span><span>{</span></div></div><div><div><span>    </span><span>return</span><span> </span><span>tracing</span><span>.</span><span>enterSpan</span><span>(</span><span>"handleRequest"</span><span>,</span><span> </span><span>async</span><span> </span><span>(</span><span>span</span><span>)</span><span> </span><span>=></span><span> </span><span>{</span></div></div><div><div><span><span>      </span></span><span>span</span><span>.</span><span>setAttribute</span><span>(</span><span>"url.path"</span><span>,</span><span> </span><span>new</span><span> </span><span>URL</span><span>(</span><span>request</span><span>.</span><span>url</span><span>)</span><span>.</span><span>pathname</span><span>)</span><span>;</span></div></div><div><div><span>      </span><span>const</span><span> </span><span>data</span><span> </span><span>=</span><span> </span><span>await</span><span> </span><span>env</span><span>.</span><span>MY_KV</span><span>.</span><span>get</span><span>(</span><span>"key"</span><span>)</span><span>;</span></div></div><div><div><span>      </span><span>return</span><span> </span><span>new</span><span> </span><span>Response</span><span>(</span><span>data</span><span>)</span><span>;</span></div></div><div><div><span>    </span><span>}</span><span>)</span><span>;</span></div></div><div><div><span>  </span><span>},</span></div></div><div><div><span>};</span></div></div>

Spans nest automatically based on the JavaScript async context, and are auto-ended when the callback returns or its returned promise settles. The Span object provides setAttribute(key, value) for attaching metadata and an isTraced property to check whether the current request is being sampled.

Tracing must be enabled in your Wrangler configuration for spans to be recorded.

For full API details and examples, refer to Custom spans.