[DOCS] Agent SDK and headless tracing docs missing TRACEPARENT/TRACESTATE parent-linking behavior

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:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/observability | Primary 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-usage | Traces reference documents exporter vars and Bash subprocess TRACEPARENT, but not SDK/headless parent trace linking or TRACESTATE |
| https://code.claude.com/docs/en/headless | CLI/headless entry point for claude -p; no tracing/linking guidance |
| https://code.claude.com/docs/en/agent-sdk/typescript | options.env reference is where TypeScript users look for per-call environment behavior |
| https://code.claude.com/docs/en/agent-sdk/python | ClaudeAgentOptions.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