[DOCS] Dynamic headers docs omit `otelHeadersHelper` failure diagnostics

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Dynamic headers / otelHeadersHelper troubleshooting

Current Documentation

The page currently says:

### Dynamic headers For enterprise environments that require dynamic authentication, you can configure a script to generate headers dynamically. Dynamic headers apply only to the http/protobuf and http/json protocols. The grpc exporter uses only the static OTEL_EXPORTER_OTLP_HEADERS value. Add to your .claude/settings.json: "otelHeadersHelper": "/bin/generate_opentelemetry_headers.sh" The headers helper script runs at startup and periodically thereafter to support token refresh. By default, the script runs every 29 minutes. Customize the interval with the CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS environment variable.

What's Wrong or Missing?

Changelog v2.1.149 says:

Fixed otelHeadersHelper failing silently when the script path contains spaces; helper failures are now reported in /doctor and the debug log

The current Dynamic headers section explains how to configure otelHeadersHelper, but it does not tell readers how helper execution failures surface after v2.1.149.

A. Missing failure-diagnostics guidance

The page does not mention that otelHeadersHelper failures are now reported in /doctor and in the debug log, so users troubleshooting broken dynamic OTEL authentication have no feature-specific pointer to the right diagnostics.

B. Missing note about the path-with-spaces fix

The page also does not note that v2.1.149 fixes the silent-failure case when the helper script path contains spaces, which is a practical setup detail for common install locations.

Suggested Improvement

Add a short troubleshooting note under Dynamic headers, for example:

If otelHeadersHelper fails, Claude Code v2.1.149 and later reports the failure in /doctor and in the debug log. Helper paths that contain spaces are supported; store the full path as the JSON string value for otelHeadersHelper.

Also add a short cross-reference to the existing configuration-debugging docs so readers know where to inspect the debug log when dynamic headers are not being applied.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/monitoring-usage | 251-277 | Dynamic headers setup and refresh behavior for otelHeadersHelper |
| https://code.claude.com/docs/en/settings | 227 | otelHeadersHelper setting reference points readers to the monitoring page |

Related documentation:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/debug-your-config | 27-28, 45-47 | Generic /doctor and /debug guidance that could be cross-linked from the OTEL helper docs |

Total scope: 2 pages affected, with 1 related troubleshooting page

Version: v2.1.149