> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://www.comet.com/docs/opik/llms.txt.

# Observability for Claude Agent SDK with Opik

> Configure Claude Code telemetry and OTLP export settings with clear signal and compatibility expectations for 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.

> **Note**
>
> Opik ingests OTel **trace spans**. Claude Code emits spans when you set
> `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` and `OTEL_TRACES_EXPORTER=otlp`.
> Prompt, tool I/O, and assistant output are **redacted by default** and are only captured on
> spans once you enable the content flags and the detailed-tracing beta below.

## Opik OTLP endpoint modes

For full endpoint/header details, see [Opik OpenTelemetry overview](/integrations/opentelemetry).

#### Opik Cloud

```bash wordWrap
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)

#### Enterprise deployment

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=https://<comet-deployment-url>/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`

#### Self-hosted instance

```bash wordWrap
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:5173/api/v1/private/otel
export OTEL_EXPORTER_OTLP_HEADERS='projectName=<your-project-name>'
```

Required headers:

* none by default (depends on your auth setup)

Optional headers:

* `projectName` (recommended)
* auth headers if your instance enforces auth

## Minimal setup for full trace visibility

This is the minimal set of environment variables that captures the **user prompt, tool
input/output, and assistant output** as spans in Opik (Opik Cloud shown; swap the endpoint for
your deployment mode above). Set these before starting your Claude Agent SDK app, or `claude -p`
(non-interactive) runs.

> **Note**
>
> Assistant output (block 4) relies on the detailed-tracing beta, which is only ungated for the
> Claude Agent SDK and non-interactive `claude -p`. In an **interactive** `claude` session that beta
> is gated, so you will get the user prompt and tool I/O but **not** `response.model_output`.

```bash wordWrap
# 1. Enable Claude Code telemetry and trace-span emission
export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

# 2. Export traces to Opik
export OTEL_TRACES_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
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>'

# 3. Un-redact content (prompt + tool input/output)
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1
export OTEL_LOG_TOOL_CONTENT=1

# 4. Capture assistant/AI output on spans (detailed-tracing beta)
export ENABLE_BETA_TRACING_DETAILED=1
export BETA_TRACING_ENDPOINT=https://www.comet.com/opik/api/v1/private/otel
```

### Why each block matters

* **Blocks 1-2** get `claude_code.*` spans into Opik. Without `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1` Claude Code emits only metrics/logs (no spans), and nothing appears in Opik.
* **Block 3** un-redacts the user prompt and tool input/output, which are redacted by default.
* **Block 4** is required for **assistant/AI output**. Claude Code only puts response text on spans (`response.model_output`) under the detailed-tracing beta; otherwise it goes to the OTel *logs* signal, which Opik does not ingest. `BETA_TRACING_ENDPOINT` is a standard OTLP base URL — point it at the same Opik endpoint. Its exporter reuses `OTEL_EXPORTER_OTLP_HEADERS` (block 2), so the `Authorization` / `Comet-Workspace` headers Opik Cloud and Enterprise require are sent automatically; no separate header variable is needed. For the Claude Agent SDK and other non-interactive (`claude -p`) runs, this beta needs no additional server-side enablement.

> **Note**
>
> `OTEL_LOG_ASSISTANT_RESPONSES=1` also un-redacts response text, but on the OTel logs signal — which Opik has no receiver for. Use block 4 (detailed-tracing beta) to get assistant output into Opik.

## Validation

1. Start your Claude Agent SDK app (or `claude -p`) with the variables above set.
2. Open the target project in Opik and find the `claude_code.interaction` trace.
3. Confirm the spans carry content: the user prompt (trace input), `tool_input` / tool output on `claude_code.tool` spans, and `response.model_output` on `claude_code.llm_request` spans.

## Source references

* [Claude Code monitoring (official)](https://code.claude.com/docs/en/monitoring-usage)
* [Opik OpenTelemetry overview](/integrations/opentelemetry)
* [OpenTelemetry SDK environment variables](https://opentelemetry.io/docs/specs/otel/configuration/sdk-environment-variables/)