OpenTelemetry Observability for Claude Agent SDK Agents

Overview

The Claude Agent SDK can export traces, metrics, and log events as OpenTelemetry data to any OTLP backend. The SDK runs the Claude Code CLI as a child process; the CLI has the OpenTelemetry instrumentation and exports directly, while the SDK passes configuration through as environment variables.

Enable export

Telemetry is off until you set CLAUDE_CODE_ENABLE_TELEMETRY=1 and choose at least one exporter. The three signals are independent:

const otelEnv = {
  CLAUDE_CODE_ENABLE_TELEMETRY: "1",
  CLAUDE_CODE_ENHANCED_TELEMETRY_BETA: "1",
  OTEL_TRACES_EXPORTER: "otlp",
  OTEL_METRICS_EXPORTER: "otlp",
  OTEL_LOGS_EXPORTER: "otlp",
  OTEL_EXPORTER_OTLP_PROTOCOL: "http/protobuf",
  OTEL_EXPORTER_OTLP_ENDPOINT: "https://collector.example.com:4318",
};
// TS replaces the inherited env, so spread process.env:
const options = { env: { ...process.env, ...otelEnv } };

In Python, env merges over the inherited environment. Do not use the console exporter through the SDK; stdout is its message channel.

Read agent traces

With traces enabled, each step becomes a span: claude_code.interaction (a turn), claude_code.llm_request (each model call), claude_code.tool (each tool, with permission-wait and execution children), and claude_code.hook. Spans carry a session.id attribute so you can group multiple query() calls in one session.

Link traces to your app

The SDK propagates W3C trace context into the CLI: if you call query() while an OpenTelemetry span is active, the agent run nests inside your span. Set TRACEPARENT in options.env to pin a specific parent.

Tag and attribute

Override OTEL_SERVICE_NAME and add OTEL_RESOURCE_ATTRIBUTES to filter by agent and attach deployment metadata. For multi-user apps, inject percent-encoded enduser.id/tenant.id resource attributes per call to build a per-user audit trail.

Control sensitive data

Telemetry is structural by default (durations, model/tool names, token counts). Content is added only with opt-in vars: OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, OTEL_LOG_TOOL_CONTENT, and OTEL_LOG_RAW_API_BODIES. Leave these unset unless your pipeline is approved to store that data.

Flush short runs

Metrics export every 60s, traces/logs every 5s by default. For short tasks, lower OTEL_METRIC_EXPORT_INTERVAL, OTEL_LOGS_EXPORT_INTERVAL, and OTEL_TRACES_EXPORT_INTERVAL so data reaches the collector before exit.

Source

• Observability with OpenTelemetry: https://code.claude.com/docs/en/agent-sdk/observability