claude-code - 💡(How to fix) Fix [DOCS] OpenTelemetry docs do not explain that subprocesses no longer inherit `OTEL_*` variables [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

"Traces (beta)" / subprocess trace propagation

Current Documentation

The monitoring page 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.

And the hooks reference currently says:

Handlers run in the current directory with Claude Code's environment.

The Agent SDK observability page also 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:

The CLI also forwards TRACEPARENT to every Bash and PowerShell command it runs. If a command launched through the Bash tool emits its own OpenTelemetry spans, those spans nest under the claude_code.tool.execution span that wraps the command.

What's Wrong or Missing?

A. The telemetry docs explain trace-context propagation but not exporter-config scrubbing

As of v2.1.128, Bash, hooks, MCP, and LSP subprocesses no longer inherit Claude Code's OTEL_* environment variables. That means an OTEL-instrumented child process no longer automatically picks up the CLI's own OTEL_EXPORTER_OTLP_ENDPOINT, headers, or related exporter settings.

B. Other pages still imply broader environment inheritance than users now get

The hooks reference says handlers run with Claude Code's environment, and the observability docs discuss subprocess trace linking through TRACEPARENT. Without an explicit note about OTEL_* scrubbing, readers can reasonably expect OTEL-instrumented subprocesses to export through the same collector automatically. After v2.1.128, they need their own OTEL exporter configuration if they should emit telemetry.

Suggested Improvement

Add a note to the monitoring page that distinguishes trace-context propagation from exporter configuration, for example:

Claude Code forwards W3C trace context (TRACEPARENT, and where applicable TRACESTATE) to supported subprocesses for parent/child trace linking, but subprocesses do not inherit Claude Code's OTEL_* exporter variables. If a Bash command, hook, MCP server, or LSP server should export its own OpenTelemetry data, configure its OTEL exporter environment explicitly.

Also add short cross-references from the hooks and Agent SDK observability pages so users do not infer that "inherits Claude Code's environment" includes Claude Code's own OTLP endpoint and exporter settings.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 3 pages affected

Version note: This gap matters for the v2.1.128 behavior change where subprocesses stop inheriting Claude Code's OTEL_* environment variables.