Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Agent SDK and headless tracing docs missing TRACEPARENT/TRACESTATE parent-linking behavior [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#48862•Fetched 2026-04-16 06:48:54
View on GitHub
Comments
0
Participants
1
Timeline
3
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×3
RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-sdk/observability

Section/Topic

"How telemetry flows from the SDK" and "Enable telemetry export" for Agent SDK tracing, plus the corresponding headless claude -p tracing guidance.

Current Documentation

The SDK observability page currently says:

Configuration is passed as environment variables. By default, the child process inherits your application's environment, so you can configure telemetry in either of two places:

  • Process environment: set the variables in your shell, container, or orchestrator before your application starts. Every query() call picks them up automatically with no code change. This is the recommended approach for production deployments.
  • Per-call options: set the variables in ClaudeAgentOptions.env (Python) or options.env (TypeScript). Use this when different agents in the same process need different telemetry settings. In Python, env is merged on top of the inherited environment. In TypeScript, env replaces the inherited environment entirely, so include ...process.env in the object you pass.

The tracing reference currently says:

When tracing is active, Bash and PowerShell subprocesses automatically inherit a TRACEPARENT environment variable containing the W3C trace context of the active tool execution span. This lets any subprocess that reads TRACEPARENT parent its own spans under the same trace, enabling end-to-end distributed tracing through scripts and commands that Claude runs.

No current code.claude.com page documents that SDK or headless sessions themselves can read inbound TRACEPARENT and TRACESTATE environment variables to link Claude Code's spans into an existing distributed trace.

What's Wrong or Missing?

Changelog v2.1.110 added support for SDK/headless sessions to read TRACEPARENT/TRACESTATE from the environment for distributed trace linking, but the docs only cover exporter configuration and downstream subprocess TRACEPARENT propagation.

What's missing is the user-facing guidance for the new inbound trace-linking behavior:

A. The feature itself is undocumented

There is no documentation that claude -p, Agent SDK Python, or Agent SDK TypeScript can join an existing W3C trace by reading TRACEPARENT and TRACESTATE from the environment.

B. The supported variables and semantics are unclear

The docs do not say whether TRACESTATE is optional, when these variables are read, or which Claude Code spans become children of the supplied parent context.

C. The SDK integration point is not explained

The docs describe options.env / ClaudeAgentOptions.env, but they do not connect those APIs to distributed trace linking, so SDK users have no discoverable way to use the new behavior.

Suggested Improvement

Add a dedicated subsection such as Link Claude Code sessions into an existing trace to https://code.claude.com/docs/en/agent-sdk/observability and cross-link it from https://code.claude.com/docs/en/headless and https://code.claude.com/docs/en/monitoring-usage.

That update should:

  1. Document TRACEPARENT and TRACESTATE as supported inbound environment variables for SDK and claude -p runs when tracing is enabled.
  2. State that the values use W3C Trace Context formatting and clarify whether TRACESTATE is optional.
  3. Explain what gets linked (for example, the session's top-level interaction/root spans attaching to the provided parent context).
  4. Show one CLI example and one Python/TypeScript SDK example using shell env vars, ClaudeAgentOptions.env, and options.env.
  5. Distinguish this inbound trace-linking feature from the already-documented downstream subprocess TRACEPARENT propagation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageContext
https://code.claude.com/docs/en/agent-sdk/observabilityPrimary SDK tracing guide; says env vars are passed through but does not document inbound trace-context env vars
https://code.claude.com/docs/en/monitoring-usageTraces reference documents exporter vars and Bash subprocess TRACEPARENT, but not SDK/headless parent trace linking or TRACESTATE
https://code.claude.com/docs/en/headlessCLI/headless entry point for claude -p; no tracing/linking guidance
https://code.claude.com/docs/en/agent-sdk/typescriptoptions.env reference is where TypeScript users look for per-call environment behavior
https://code.claude.com/docs/en/agent-sdk/pythonClaudeAgentOptions.env reference is where Python users look for per-call environment behavior

Total scope: 5 pages affected

Source: Changelog v2.1.110

Exact changelog entry:

SDK/headless sessions now read TRACEPARENT/TRACESTATE from the environment for distributed trace linking

extent analysis

TL;DR

Add documentation for linking Claude Code sessions into an existing trace by reading TRACEPARENT and TRACESTATE environment variables.

Guidance

  • Update the SDK observability page to include a dedicated subsection on linking Claude Code sessions into an existing trace, covering supported inbound environment variables, their semantics, and usage examples.
  • Clarify the relationship between options.env/ClaudeAgentOptions.env and distributed trace linking in the SDK documentation.
  • Provide examples for using TRACEPARENT and TRACESTATE with the CLI and SDKs (Python and TypeScript) to demonstrate how to link sessions into an existing trace.
  • Ensure the documentation distinguishes between inbound trace-linking and downstream subprocess TRACEPARENT propagation.
  • Review and update the affected pages (agent-sdk/observability, monitoring-usage, headless, agent-sdk/typescript, agent-sdk/python) to reflect the new documentation.

Example

// Example TypeScript usage
const options = {
  env: {
    TRACEPARENT: '00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01',
    TRACESTATE: 'congo=t61rcG0yMzQ=',  // Optional
    ...process.env
  }
};

Notes

The exact behavior and requirements for TRACESTATE (whether it's optional, its format, etc.) should be clarified in the documentation to ensure users understand how to correctly use these environment variables for distributed trace linking.

Recommendation

Apply workaround by adding the suggested documentation subsection and updating the affected pages to provide clear guidance on using TRACEPARENT and TRACESTATE for linking Claude Code sessions into an existing trace. This will improve the usability of the feature and reduce confusion among users.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#api#conversation history#tool integration#LLM response#environment variable

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Agent SDK and headless tracing docs missing TRACEPARENT/TRACESTATE parent-linking behavior [1 participants]