[DOCS] OpenTelemetry docs omit managed-endpoint precedence over signal-specific overrides

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The managed-settings note and the Common configuration variables table under OpenTelemetry configuration.

Current Documentation

The monitoring page currently says:

Managed settings can be distributed via MDM (Mobile Device Management) or other device management solutions. Environment variables defined in the managed settings file have high precedence and can't be overridden by users.

The same page describes the endpoint variables this way:

OTEL_EXPORTER_OTLP_ENDPOINT — OTLP collector endpoint for all signals

OTEL_EXPORTER_OTLP_METRICS_ENDPOINT — OTLP metrics endpoint, overrides general setting

OTEL_EXPORTER_OTLP_LOGS_ENDPOINT — OTLP logs endpoint, overrides general setting

What's Wrong or Missing?

The table explains ordinary signal-specific endpoint precedence but does not say how that rule changes when OTEL_EXPORTER_OTLP_ENDPOINT is supplied by managed settings. Claude Code v2.1.217 fixes lower-scope signal-specific settings so they no longer redirect telemetry away from a managed general endpoint.

Without a managed-scope exception in the table, an administrator may read “overrides general setting” as permission for a user or project OTEL_EXPORTER_OTLP_METRICS_ENDPOINT or OTEL_EXPORTER_OTLP_LOGS_ENDPOINT value to route data to a different collector. That makes the documented precedence incomplete for enterprise telemetry policy and does not explain the security-relevant behavior introduced by the fix.

Suggested Improvement

Clarify the endpoint table and managed-settings note with an explicit precedence example. The documentation should:

• State that a managed OTEL_EXPORTER_OTLP_ENDPOINT governs all signals and cannot be redirected by lower-scope signal-specific endpoint variables.
• Distinguish the ordinary signal-specific override behavior from the managed-policy behavior.
• Explain whether a signal-specific endpoint declared in the same managed settings scope is allowed to specialize the managed endpoint, and show the supported configuration shape.
• Add a managed-settings example that makes the effective endpoint for metrics, logs, and traces unambiguous.
• Link the general settings-precedence explanation to this OpenTelemetry-specific rule.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/monitoring-usage | 63-83 | Managed-settings note and general versus signal-specific OTLP endpoint table |
| https://code.claude.com/docs/en/settings | 50-60 | Generic managed-scope precedence that does not spell out the OTEL endpoint exception |
| https://code.claude.com/docs/en/env-vars | 102-108 | General env precedence across settings files |

Total scope: 3 Claude Code pages should describe the same managed OTEL endpoint policy.

The relevant release is Claude Code v2.1.217. The release entry is listed in the Claude Code changelog under version 2.1.217.