PythonFrameworks

Observability for Claude Agent SDK with Opik

Claude Code telemetry is configured through environment variables.

When this guide applies

Use this guide when you want to configure Claude Code’s official OpenTelemetry settings and align endpoint/header values with your Opik deployment mode.

Claude Code’s monitoring docs currently describe OTel metrics and events/logs exporters. Opik tracing views are span-based. Verify your pipeline emits spans if your goal is trace visualization in Opik.

Opik OTLP endpoint modes

For full endpoint/header details, see Opik OpenTelemetry overview.

$export OTEL_EXPORTER_OTLP_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
$export OTEL_EXPORTER_OTLP_HEADERS='Authorization=<your-api-key>,Comet-Workspace=<your-workspace>,projectName=<your-project-name>'

Required headers:

  • Authorization
  • Comet-Workspace

Optional headers:

  • projectName (recommended for deterministic routing)

Claude telemetry configuration (official pattern)

Intent: Enable Claude Code telemetry and route supported OTel signals to your collector/backend.

Applies when: You run Claude Code with telemetry enabled via environment variables.

Required fields:

  • CLAUDE_CODE_ENABLE_TELEMETRY=1
  • at least one exporter (OTEL_METRICS_EXPORTER or OTEL_LOGS_EXPORTER)

Optional fields:

  • OTEL_EXPORTER_OTLP_PROTOCOL
  • OTEL_EXPORTER_OTLP_ENDPOINT
  • OTEL_EXPORTER_OTLP_HEADERS
  • per-signal overrides such as OTEL_EXPORTER_OTLP_METRICS_ENDPOINT

Minimal valid setup:

$export CLAUDE_CODE_ENABLE_TELEMETRY=1
$export OTEL_METRICS_EXPORTER=otlp
$export OTEL_LOGS_EXPORTER=otlp
$export OTEL_EXPORTER_OTLP_PROTOCOL=grpc
$export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
$# Optional if your collector/export path requires auth
$export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
$claude

Validation

  1. Start Claude with telemetry enabled.
  2. Confirm your OTLP backend receives claude_code.* metrics/events.
  3. If targeting Opik trace views, verify spans are emitted by your pipeline; metrics/logs alone will not appear as traces.

Source references