[Workers] Document startActiveSpan and span.end() tracing APIs

[nevikashah]

Summary

Documents the new tracing.startActiveSpan() and span.end() APIs added in workerd MR !263. These APIs allow manual span lifetime management for instrumenting operations that outlive a single callback, such as stream pipelines.

Key additions to the custom spans page:

• tracing.startActiveSpan(name, callback, ...args) API reference with parameters, behavior, and examples
• span.end() method documentation on the Span object
• Stream instrumentation example showing the primary use case (span stays open until stream drains)
• Comparison table between enterSpan and startActiveSpan
• Updated TypeScript type declarations
• Updated limitations section

The docs call out an important caveat: startActiveSpan provides manual lifetime management but only in an "active during callback" shape — the span is the active context parent only during the callback, not for the full span lifetime. This is explained via a caution admonition and the comparison table.

Documentation checklist

• The change adheres to the documentation style guide.

[github-actions]

This pull request requires reviews from CODEOWNERS as it changes files that match the following patterns:

Pattern	Owners
/src/content/docs/workers/observability/	@irvinebroque, @mikenomitch, @nevikashah, @cloudflare/product-owners, @vy-ton

[ask-bonk]

Review Summary

This PR adds clear, well-structured documentation for the new startActiveSpan and span.end() tracing APIs. The stream instrumentation example effectively demonstrates the primary use case, and the comparison table between enterSpan and startActiveSpan is a helpful addition.

What changed

• Added tracing.startActiveSpan(name, callback, ...args) API reference with parameters, behavior, and examples
• Added span.end() method documentation on the Span object
• Added a stream instrumentation example using TransformStream
• Added a comparison table for choosing between enterSpan and startActiveSpan
• Updated TypeScript type declarations to include startActiveSpan and end()
• Removed the "No manual span lifetime management" limitation (now supported)

Issues flagged

1. Beta config note removal — The <Render file="tracing-beta-config-note" product="workers" /> partial was removed. That partial contains important forward-looking context about observability.enabled behavior and future compatibility_date requirements. Please confirm this removal is intentional. If tracing is still in beta (the sidebar.badge.text: Beta remains), this note may still be valuable.

2. Code block indentation — The TypeScript code examples throughout the file were changed from 2-space indentation to tabs. This affects every existing code block in the file, not just the new content. Please confirm this is intentional or revert to 2-space indentation to match the original file style.

3. Minor suggestion — In the bare ts snippets for capturedSpan and mySpan, consider adding type annotations (let capturedSpan: Span;, let mySpan: Span;) for clarity.

Overall a solid addition to the tracing docs. Once the two questions above are addressed, this should be good to merge.

[ask-bonk]

Suggested code changes (inline references)

Line 37 (## Create a custom span) — Was the removal of <Render file="tracing-beta-config-note" product="workers" /> intentional? That partial contains forward-looking info about observability.enabled and compatibility_date. If tracing is still beta (sidebar badge remains), this note should probably stay.

Lines 50–63 (first TypeScriptExample code block) — The code examples throughout this file were changed from 2-space indentation to tabs. This affects every existing code block, not just the new content. Please confirm this is intentional, or revert existing examples to 2-space indentation to match the original file style.

Line 180 (let capturedSpan;) — Consider adding a type annotation for clarity: let capturedSpan: Span;.

Line 239 (let mySpan;) — Consider adding a type annotation for clarity: let mySpan: Span;.

See the main review comment above for full context.

[ask-bonk]

I have completed the review of PR #31853 in cloudflare/cloudflare-docs.

What was done

1. Labels applied: Added documentation and content:new.
2. Review posted: A summary review comment with the analysis below.
3. Inline comments posted: A follow-up comment referencing specific lines with suggestions.

PR Summary

• Title: [Workers] Document startActiveSpan and span.end() tracing APIs — follows repo conventions.
• Changes: Adds tracing.startActiveSpan() and span.end() API docs, a stream instrumentation example, a comparison table, updated TypeScript declarations, and removes the outdated “No manual span lifetime management” limitation.

Issues Flagged

#	Issue	Severity
1	Removed beta config note (tracing-beta-config-note partial) — contains important forward-looking info about observability.enabled and compatibility_date requirements. If tracing is still beta (sidebar badge is still present), this note should probably stay.	Needs maintainer attention
2	Code block indentation changed from 2 spaces → tabs throughout the entire file, affecting every existing code example. This is inconsistent with the original file style.	Needs maintainer attention
3	Minor: let capturedSpan; and let mySpan; are untyped in snippets. Suggested adding : Span for clarity.	Suggestion

No frontmatter errors, broken internal links, or MDX syntax issues were found. The new content is well-structured and the caution admonition correctly calls out the async-context limitation of startActiveSpan.

github run

[github-actions]

Preview URL: https://067a3e04.preview.developers.cloudflare.com
Preview Branch URL: https://workers-start-active-span-docs.preview.developers.cloudflare.com

Files with changes (up to 15)

Original Link	Updated Link
https://developers.cloudflare.com/workers/observability/traces/custom-spans/	https://workers-start-active-span-docs.preview.developers.cloudflare.com/workers/observability/traces/custom-spans/

[nevikashah]

Thanks for the review! Addressing each point:

1. Beta config note removal — Intentional. The partial was removed at the PR author's request.

2. Code block indentation (2-space → tabs) — This is the repo's Prettier config. Running pnpm run format converts all code blocks to tabs. Reverting would fail CI's format:core:check step.

3. Type annotations (let capturedSpan: Span) — Intentionally omitted. Span is not importable as a standalone type in these snippets, so adding the annotation would cause TypeScript errors if readers copy-paste the code. The type is inferred from the callback parameter.

[irvinebroque]

Does this mean we can make a little shim that bridges between this and opentelemetry-js?