Quartz 4

note 2026-04-11 00-00-00

2 min read

Context: Studying Claude Code source (claude-code-source-code-full, backup branch)

Claude Code OTEL/Telemetry Support

Core Toggle

  • CLAUDE_CODE_ENABLE_TELEMETRY - master switch for customer-facing OTEL telemetry

Standard OTEL Variables

Exporter selection:

  • OTEL_METRICS_EXPORTER - otlp, console, prometheus, or none
  • OTEL_LOGS_EXPORTER - otlp, console, or none
  • OTEL_TRACES_EXPORTER - otlp, console, or none

Protocol/endpoint:

  • OTEL_EXPORTER_OTLP_PROTOCOL - global: grpc, http/json, http/protobuf
  • OTEL_EXPORTER_OTLP_ENDPOINT - OTLP endpoint URL
  • OTEL_EXPORTER_OTLP_HEADERS - comma-separated key=value auth headers
  • Per-signal protocol overrides: OTEL_EXPORTER_OTLP_METRICS_PROTOCOL, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL

Export intervals (ms):

  • OTEL_METRIC_EXPORT_INTERVAL (default 60000)
  • OTEL_LOGS_EXPORT_INTERVAL (default 5000)
  • OTEL_TRACES_EXPORT_INTERVAL (default 5000)
  • OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE (default delta)

Content Logging

  • OTEL_LOG_USER_PROMPTS - truthy: include full user prompts in spans (otherwise <REDACTED>)
  • OTEL_LOG_TOOL_CONTENT - truthy: add tool content/output as span events

Enhanced Telemetry (Beta)

  • CLAUDE_CODE_ENHANCED_TELEMETRY_BETA / ENABLE_ENHANCED_TELEMETRY_BETA - toggle span-level tracing (interactions, LLM requests, tools)
  • Gated by build flag ENHANCED_TELEMETRY_BETA
  • For ant users: enabled by default
  • For external users: controlled by GrowthBook enhanced_telemetry_beta flag

Beta Detailed Tracing

  • ENABLE_BETA_TRACING_DETAILED=1 + BETA_TRACING_ENDPOINT - enables system prompt logging, per-agent message tracking, new_context attributes
  • Separate HTTP endpoint from main OTEL (used for both traces and logs)
  • External users also need SDK/headless mode or GrowthBook tengu_trace_lantern gate

Perfetto Tracing (Ant-only)

  • CLAUDE_CODE_PERFETTO_TRACE - set to 1 (writes to ~/.claude/traces/) or a file path
  • CLAUDE_CODE_PERFETTO_WRITE_INTERVAL_S - periodic write interval in seconds (default: write only on exit)
  • Gated by build flag PERFETTO_TRACING (dead-code eliminated from external builds)
  • Output: Chrome Trace Event JSON, viewable in ui.perfetto.dev

Shutdown/Flush Timeouts

  • CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS (default 2000) - max wait for provider shutdown on exit
  • CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS (default 5000) - max wait for flush (e.g. before logout)

Internal/Ant Build Variables

When USER_TYPE=ant, these build-time vars are copied to their OTEL equivalents:

  • ANT_OTEL_METRICS_EXPORTER → OTEL_METRICS_EXPORTER
  • ANT_OTEL_LOGS_EXPORTER → OTEL_LOGS_EXPORTER
  • ANT_OTEL_TRACES_EXPORTER → OTEL_TRACES_EXPORTER
  • ANT_OTEL_EXPORTER_OTLP_PROTOCOL → OTEL_EXPORTER_OTLP_PROTOCOL
  • ANT_OTEL_EXPORTER_OTLP_ENDPOINT → OTEL_EXPORTER_OTLP_ENDPOINT
  • ANT_OTEL_EXPORTER_OTLP_HEADERS → OTEL_EXPORTER_OTLP_HEADERS

Other

  • USER_TYPE - when ant, enables internal paths (Perfetto, BigQuery, thinking output in traces)
  • CLAUDE_CODE_WORKSPACE_HOST_PATHS - pipe-delimited workspace paths, attached to log events only
  • CLAUDE_CODE_OTEL_HEADERS_HELPER_DEBOUNCE_MS - debounce for otelHeadersHelper setting
  • otelHeadersHelper (settings.json) - external command for dynamic OTEL auth header refresh

Build-Time Feature Flags

  • ENHANCED_TELEMETRY_BETA - gates enhanced span-level tracing
  • PERFETTO_TRACING - gates Perfetto trace code

Key Source Files

  • src/utils/telemetry/instrumentation.ts - OTEL provider setup, exporter creation, bootstrap
  • src/utils/telemetry/sessionTracing.ts - span management (interaction, LLM, tool spans)
  • src/utils/telemetry/betaSessionTracing.ts - beta detailed tracing with hash-based dedup
  • src/utils/telemetry/perfettoTracing.ts - Chrome Trace Event format output
  • src/utils/telemetry/events.ts - OTEL event logging
  • src/utils/telemetry/bigqueryExporter.ts - BigQuery metrics for API/C4E/Teams customers

Graph View