Observagent
CLI integration · Windows · macOS · Linux

Connect Claude Code to Observagent.

Use Claude Code's built-in OpenTelemetry exporters to send logs, metrics, and beta traces directly to Observagent.

Select OS Verify delivery
Claude CodeRuntime telemetry
OTLP over HTTPSHTTP/protobuf
ObservagentLogs + metrics + traces
How it works

Use Claude Code's built-in OpenTelemetry export

Claude Code exports runtime events as OTLP logs, usage counters as OTLP metrics, and optional distributed spans as OTLP traces. Observagent accepts all three signals over OTLP/HTTP protobuf, so this integration does not require a local proxy or an additional SDK.

  • Logs include Claude Code events such as API requests and tool activity.
  • Metrics include sessions, token usage, cost estimates, and supported code activity.
  • Traces are a Claude Code beta feature and connect prompts, model requests, and tool execution.
  • Telemetry begins after configuration and restart; existing sessions are not backfilled.
Before you begin

Minimum required plan

Claude Pro (subscription route).

  • Claude Free does not include Claude Code. Pro is the lowest qualifying subscription; higher plans also qualify when Claude Code access is enabled.
  • Alternatively, use billed Claude Console or approved cloud-provider API access without a Claude subscription. API usage is billed separately.
Observagent accessPrepare an Observagent project with monitoring and the required signals enabled, plus a valid project key with telemetry:write permission.

Requirements reviewed on .

Select OS

Integration steps

Select a platform to see commands and paths for your computer. Project setup and delivery verification are shared across platforms.

WindowsPowerShell
  1. Step 1

    Create a project and project key

    In Observagent Settings, create or select a project, enable Logs, Metrics, and Traces, and turn monitoring on. Choose Connect source and generate a project key with telemetry:write permission. Copy it when shown.

    • Use a separate key for each project and keep it out of source control. Replacing a connection revokes its earlier key.
    • The generic collector endpoint is https://dashboard.observagent.cloud.
  2. Step 2

    Open your user-level Claude Code settings

    Back up and edit ~/.claude/settings.json for the user who runs Claude Code. Add env inside the existing top-level JSON object instead of pasting a second object.

    • On Windows, the user file is normally C:\Users\YOUR_NAME\.claude\settings.json.
    • Claude Code ignores OTLP destination variables in repository-level .claude/settings.json. Use user settings, managed settings, or the shell that launches Claude Code.
    • Keep one valid top-level JSON object. Merge env alongside existing settings such as theme and autoUpdatesChannel.
    PowerShell
    claude --version
$config = Join-Path $HOME ".claude\settings.json"
New-Item -ItemType Directory -Force (Split-Path $config) | Out-Null
if (Test-Path $config) { Copy-Item $config "$config.backup" }
notepad $config
  3. Step 3

    Add the OTLP exporters

    Merge these values into the existing user settings and replace YOUR_PROJECT_KEY with the complete project key. Preserve your other settings.

    • Use a literal space after Bearer. Do not use Bearer%20YOUR_PROJECT_KEY; the exporter sends %20 literally.
    • Use the generic endpoint without /v1/logs, /v1/metrics, or /v1/traces. Claude Code appends the path for each signal.
    ~/.claude/settings.json · JSON
    {
  "autoUpdatesChannel": "latest",
  "theme": "dark",
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://dashboard.observagent.cloud",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer YOUR_PROJECT_KEY"
  }
}
  4. Step 4

    Restart Claude Code and verify delivery

    Fully close Claude Code, start a new process with a debug log, and complete a model request. Allow up to 60 seconds for the default metric export interval, then check each enabled signal in Observagent Telemetry Data.

    • Select the Claude project, All sources, and a time range that includes the test.
    • Look for claude_code.api_request, claude_code.token.usage, or claude_code.cost.usage and recent trace spans. The Model usage chart displays the exact model identifier.
    • Successful debug output reports the first logs, traces, and metrics exports as SUCCESS. Check all three signals separately.
    PowerShell
    claude --debug-file "$env:TEMP\claude-otel-debug.log" -p "Reply with exactly: telemetry test"
Select-String -Path "$env:TEMP\claude-otel-debug.log" -Pattern "3P telemetry|OTLP|export|401|403|404|error" -CaseSensitive:$false
Troubleshooting

Diagnose exporter failures

Use the debug commands in the final setup step for the operating system selected above.

  • Missing telemetry API key: use a literal space after Bearer, confirm the real key replaced the placeholder, and restart Claude Code.
  • 401 Unauthorized: the key is missing, malformed, revoked, expired, or belongs to a replaced connection.
  • 403 Forbidden: monitoring is paused, the signal is disabled, or the key lacks telemetry:write.
  • 404 Not Found: use the generic endpoint without /v1/logs, /v1/metrics, or /v1/traces.
  • No model in the chart: starting a session is not enough. Complete a model request and check for an API-request, token, or cost record containing model.
  • Settings error: validate that settings.json contains one valid top-level JSON object.
Privacy

Keep content redacted by default

Claude Code redacts prompt text, assistant responses, tool arguments, and tool output by default. Do not enable content-export variables unless your privacy and retention policies permit that data to be stored. Observagent applies its own server-side content controls as an additional boundary.

Configuration details follow Anthropic's Claude Code monitoring documentation.