Cloudflare Workers now expose four additional OpenTelemetry‑aligned methods—tracing.startSpan(), tracing.getActiveSpan(), span.recordException(), and span.setAttributes(). These APIs let you spin up a custom span without automatically nesting it, retrieve the active span for downstream annotation, attach exception details directly to a span, and apply multiple attributes in a single call. For engineers who instrument AI pipelines, platform services, or security tooling, the change translates into more precise tracing data and less boilerplate when propagating context.
New Span Lifecycle Methods
The tracing.startSpan(name) call creates a span object that is independent of the current execution context. Because it does not become the active span, other spans will not automatically become its children, giving you explicit control over hierarchy. The span must be closed with span.end() once the work is finished. Complementing this, tracing.getActiveSpan() returns the span that is currently active—either a custom span you created earlier or, by default, the root span that represents the entire Worker invocation. This makes it possible for helper libraries to enrich the ongoing trace without receiving a span reference as a parameter.
Error Recording and Attribute Management
The span.recordException(exception) method records an exception event on the span. It accepts a native Error, a plain string, or an object containing code, name, or message fields, allowing flexible error payloads. Meanwhile, span.setAttributes(attributes) applies a map of key‑value pairs to the span in one operation. Both setAttribute() and setAttributes() now return the span itself, enabling fluent chaining such as span.setAttributes({foo: "bar"}).recordException(err). These additions reduce the amount of manual instrumentation code required to capture meaningful diagnostics.
Practical Integration Example
import { tracing } from "cloudflare:workers";
export default {
async fetch(request, env) {
// Add user metadata to the root span
tracing.getActiveSpan()?.setAttributes({
"user.id": user.id,
"user.plan": user.plan,
});
// Create a custom span for profile loading
const span = tracing.startSpan("load-profile");
try {
const data = await loadProfile(env, user.id);
return Response.json(data);
} catch (err) {
span.recordException(err);
throw err;
} finally {
span.end();
}
},
};
The snippet demonstrates three patterns: annotating the root span, creating an isolated span for a specific operation, and recording any exception that occurs within that operation. Because the custom span does not become active automatically, other instrumentation continues to attach to the root span unless you explicitly switch context.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
- Instrumenting fine‑grained operations no longer requires manual context propagation; use
getActiveSpan()to enrich the current trace from any depth. - Separate spans can be created for parallel or independent work without unintentionally nesting them, simplifying trace topology.
- Direct exception logging on spans improves error visibility in tracing backends, aiding root‑cause analysis for AI model failures, deployment rollbacks, or security incidents.
- Batch attribute setting reduces API calls and keeps attribute handling consistent across services.
Adopt these methods where you already emit OpenTelemetry data from Workers. Verify that your tracing backend can ingest the new span events and attribute structures, and update any alerting rules that rely on exception counts or attribute filters.