Administrator configuration

Administrators can configure OpenTelemetry settings for all users through the managed settings file. See the settings precedence for more information about how settings are applied.

Example managed settings configuration:

{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "grpc",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4317",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer example-token"
  }
}

Claude Code doesn't pass OTEL_* environment variables to the subprocesses it spawns, including the Bash tool, hooks, MCP servers, and language servers. An OpenTelemetry-instrumented application that you run through the Bash tool doesn't inherit Claude Code's exporter endpoint or headers, so set those variables directly in the command if that application needs to export its own telemetry.

How managed settings lock the OTLP destination

When you set an OTEL_EXPORTER_OTLP_* variable in managed settings, Claude Code removes conflicting developer-set variables at startup and logs a warning you can see with claude --debug. What it removes depends on which variable you set:

• Endpoints: when you set OTEL_EXPORTER_OTLP_ENDPOINT, Claude Code removes every developer-set per-signal endpoint. Developers can't point one signal at a different collector, so you don't need to also set the per-signal endpoint variables in managed settings.

• Protocols: when you set OTEL_EXPORTER_OTLP_PROTOCOL, Claude Code removes every developer-set per-signal protocol.

• Credentials: when you set OTEL_EXPORTER_OTLP_HEADERS, OTEL_EXPORTER_OTLP_CLIENT_KEY, or OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE, Claude Code removes the developer-set per-signal versions of that variable, plus every developer-set endpoint variable, generic or per-signal, since those credentials would otherwise reach a collector the managed settings didn't choose.

• Exporter selectors: OTEL_METRICS_EXPORTER, OTEL_LOGS_EXPORTER, and the beta OTEL_TRACES_EXPORTER follow normal per-key precedence. A developer's setting can still disable a signal or switch it to the console exporter, so set the selectors in managed settings too if you need them locked. Across admin sources, OTEL_LOGS_EXPORTER follows the telemetry unit while the other two selectors merge per key. Requires Claude Code v2.1.223 or later.

• Beta tracing endpoints: with detailed beta tracing active, Claude Code exports logs and traces to BETA_TRACING_ENDPOINT instead of through the logs and traces exporters. Claude Code therefore removes a developer-set BETA_TRACING_ENDPOINT whenever any of these managed settings decides either signal's destination:

  • A generic or logs/traces endpoint or credential
  • An otelHeadersHelper
  • A logs or traces exporter selector set to none, console, or empty, values that keep the signal off a collector
  • CLAUDE_CODE_ENABLE_TELEMETRY turned off

  A metrics-only endpoint or credential doesn't remove it. Before v2.1.251, a developer-set BETA_TRACING_ENDPOINT redirected the logs and traces that detailed beta tracing exports even when managed settings pinned the collector.

Claude Code doesn't remove per-signal variables that you set in managed settings itself, so you can route one signal to a different collector by setting its variable there, as the SIEM example does. If you set a per-signal credential there, Claude Code removes the developer-set endpoint for that signal.

This removal behavior changes where telemetry is delivered, not what Claude Code collects.

Before v2.1.217, every variable followed per-key settings precedence independently, so a signal-specific endpoint set in user settings or the shell redirected that signal away from the managed collector.

When the desktop app or a self-hosted environment runner launches Claude Code and names an OTLP endpoint in the environment it provides, Claude Code pins the destination the same way: the launcher's telemetry variables remove developer-set variables exactly as managed settings do. Claude Code doesn't remove variables that the launcher itself set. Requires Claude Code v2.1.251 or later.