claude-code - 💡(How to fix) Fix [DOCS] Bash tool tracing docs missing `TRACEPARENT` subprocess propagation [1 comments, 2 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/monitoring-usage

Section/Topic

Traces (beta) and Bash subprocess tracing behavior

Current Documentation

The docs currently say:

Distributed tracing exports spans that link each user prompt to the API requests and tool executions it triggers, so you can view a full request as a single trace in your tracing backend.

Tracing is off by default. To enable it, set both CLAUDE_CODE_ENABLE_TELEMETRY=1 and CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1, then set OTEL_TRACES_EXPORTER to choose where spans are sent.

And the Bash tool reference says:

The Bash tool runs each command in a separate process with the following persistence behavior:

• Working directory persists across commands. Set CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1 to reset to the project directory after each command.
• Environment variables do not persist. An export in one command will not be available in the next.

No current page explains that, when tracing is enabled, Bash subprocesses receive a W3C TRACEPARENT environment variable.

What's Wrong or Missing?

Changelog v2.1.97 added: "Improved Bash tool OTEL tracing: subprocesses now inherit a W3C TRACEPARENT env var when tracing is enabled".

The current tracing documentation explains how to enable OpenTelemetry tracing, and the Bash tool documentation explains process behavior, but neither page documents that Bash commands receive TRACEPARENT or how users can use that value to correlate their own scripts and subprocesses with Claude Code traces.

That leaves an important tracing capability undiscoverable for users who want end-to-end trace propagation through shell scripts and command chains.

Suggested Improvement

Add a short subsection in Monitoring under Traces (beta) (and cross-reference it from Tools reference) that explains:

• when tracing is enabled, Claude Code injects a W3C TRACEPARENT environment variable into Bash tool subprocesses
• this lets user-run scripts and downstream instrumented processes attach to the same distributed trace
• the variable is available per Bash command process rather than as a persisted shell export across turns

Include a minimal example such as reading TRACEPARENT inside a shell script or forwarding it to another traced process.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.97

Exact changelog entry: Improved Bash tool OTEL tracing: subprocesses now inherit a W3C TRACEPARENT env var when tracing is enabled