Telemetry Pipeline: Tool-Call Event → Batched Export

Overview

Claude Code initializes an OpenTelemetry SDK at startup and routes tool-call events through analytics and OTLP exporters, with optional BigQuery metrics and Perfetto trace correlation across agent loops fn:initializeTelemetry.

Steps

1. At startup, initializeTelemetry runs a profile checkpoint and calls bootstrapTelemetry to copy ANT_OTEL_* env vars into the standard OTEL_* slots for ant users fn:initializeTelemetry. The bootstrap also defaults metrics temporality to delta and strips console exporters when stdout is the structured SDK channel fn:bootstrapTelemetry.
2. Telemetry is gated behind CLAUDE_CODE_ENABLE_TELEMETRY, checked via a truthy env parse fn:isTelemetryEnabled interface:CLAUDE_CODE_ENABLE_TELEMETRY fn:isEnvTruthy.
3. doInitializeTelemetry guards against double-init via a module-level flag and then wires meter state fn:doInitializeTelemetry state:telemetryInitialized.
4. Metric readers are assembled by getOtlpReaders, which parses the exporter list and reads the export interval from env fn:getOtlpReaders interface:OTEL_METRICS_EXPORTER interface:OTEL_METRIC_EXPORT_INTERVAL. Exporter type strings are split and filtered by parseExporterTypes fn:parseExporterTypes.
5. For eligible users, a BigQuery metrics reader is added on a 5-minute PeriodicExportingMetricReader cadence fn:getBigQueryExportingReader. Eligibility combines 1P API customers and enterprise/team Claude.ai subscribers fn:isBigQueryMetricsEnabled fn:is1PApiCustomer fn:getSubscriptionType.
6. Trace exporters are selected by protocol (grpc / http/json / http/protobuf) via getOtlpTraceExporters, each wrapped with an OTLP exporter config that threads proxy, mTLS, and dynamic headers fn:getOtlpTraceExporters interface:OTEL_EXPORTER_OTLP_TRACES_PROTOCOL fn:getOTLPExporterConfig interface:OTEL_EXPORTER_OTLP_ENDPOINT. Log exporters follow the same pattern through getOtlpLogExporters fn:getOtlpLogExporters interface:OTEL_LOGS_EXPORTER.
7. Beta Perfetto-style tracing is set up when BETA_TRACING_ENDPOINT is defined: an OTLPTraceExporter is wrapped in a BatchSpanProcessor and attached to a BasicTracerProvider, which is registered via setTracerProvider fn:initializeBetaTracing fn:setTracerProvider. A log exporter is registered via setLoggerProvider, and meter/event-logger providers via setMeterProvider and setEventLogger fn:setLoggerProvider fn:setMeterProvider fn:setEventLogger.
8. At tool-use time, runToolUse resolves the tool, logs cancellations/errors via logEvent, and streams into checkPermissionsAndCallTool fn:runToolUse fn:checkPermissionsAndCallTool. That path records tengu_tool_use_error and validation events through the analytics sink, which either dispatches or enqueues for a deferred sink fn:logEvent state:sink state:eventQueue.
9. For sub-agents, runAgent registers the child in the Perfetto trace hierarchy (parent = parent agentId or session) so tool spans emitted during the agent loop correlate back to the spawning agent fn:runAgent. Agent definitions and memory loads also emit tengu_agent_memory_loaded into the same analytics stream fn:runInProcessTeammate.
10. On process shutdown, providers flush within bounds configured by CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS / CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS, with cleanup handlers registered via registerCleanup interface:CLAUDE_CODE_OTEL_FLUSH_TIMEOUT_MS interface:CLAUDE_CODE_OTEL_SHUTDOWN_TIMEOUT_MS fn:registerCleanup.

State touched

• state:telemetryInitialized
• state:sink
• state:eventQueue
• state:cachedOtelHeaders
• state:cachedOtelHeadersTimestamp

Decisions

No [decision:...] tokens appear in the whitelist, so no design-decision citations are available for this flow fn:initializeTelemetry.