Skip to content

Connect Claude Code To Provon

Claude Code has native OpenTelemetry support for metrics, structured log events, and distributed traces. Send its traces to Provon to inspect coding-agent sessions and run conversa

View as Markdown Open the plain-text version of this page.

Use Agent transcript sync to backfill existing sessions from ~/.claude/projects/ or when Claude Code's native trace exporter is unavailable.

Choose Signals#

Only traces are required for the Provon coding-agent workflow:

Signal Upstream status Recommendation Use in Provon
Traces Beta Required Trace explorer, conversations, diagnostic Rules, and Findings
Logs Supported Optional Independent event search through the Telemetry Read API
Metrics Supported Optional Independent usage, cost, and activity queries

Provon diagnostics build conversation evidence from spans. Claude Code logs and metrics do not enrich that span trajectory automatically. Enabling them by default creates additional ingest, storage, and potentially sensitive event data without improving trace diagnosis.

The recommended configuration therefore exports traces only. Claude Code traces currently require its enhanced telemetry beta switch. If the beta exporter is unavailable or unsuitable for production policy, use transcript sync; logs are not a substitute for traces.

Prerequisites#

  • A Provon project.
  • A project API key with telemetry:ingest.
  • A current Claude Code installation.
  • Network access to the Provon OTLP endpoint.

Check the installed version:

bash
claude --version

Configure Trace Export#

Set these variables in the shell that launches Claude Code:

bash
export PROVON_API_KEY="your_project_api_key"
export PROVON_OTEL_URL="https://otel.provon.dev/v1"

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1

export OTEL_TRACES_EXPORTER=otlp
export OTEL_LOGS_EXPORTER=none
export OTEL_METRICS_EXPORTER=none

export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="$PROVON_OTEL_URL/traces"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer $PROVON_API_KEY"

Then start Claude Code from the same shell:

bash
claude

The hosted PROVON_OTEL_URL already includes /v1. The complete trace endpoint prevents the exporter from appending another /v1.

Use http/protobuf, not grpc. Claude Code supports both, but Provon exposes only OTLP/HTTP.

Choose An Evidence Policy#

Claude Code trace content is privacy-bounded by default:

  • user prompts are redacted;
  • tool parameters and file or command details are omitted;
  • tool input and output content is omitted;
  • raw Anthropic API request and response bodies are omitted.

The trace still includes span hierarchy, timing, model, token usage, tool names, permission decisions, success, and error fields.

For diagnosis that needs the user's actual goal and tool parameters, opt into only those fields:

bash
export OTEL_LOG_USER_PROMPTS=1
export OTEL_LOG_TOOL_DETAILS=1

These variables also control content placed on trace spans; they are useful even when OTEL_LOGS_EXPORTER=none.

Tool input and output bodies carry substantially more sensitive content. Enable them only when a Rule needs command output or another tool result:

bash
export OTEL_LOG_TOOL_CONTENT=1

OTEL_LOG_TOOL_CONTENT requires tracing and can export content from files, commands, and tools. Claude Code truncates exported content attributes, but truncation is not sanitization.

Do not enable OTEL_LOG_RAW_API_BODIES for normal Provon integration. Raw bodies can contain the entire conversation history and are not required for trace exploration or diagnosis.

Verify#

Run one prompt that performs a model request and a harmless tool call, then exit Claude Code normally:

text
Inspect the current directory and summarize its top-level files. Do not modify anything.

Then:

  1. Open the same Provon project.
  2. Open Traces and select the latest Claude Code interaction.
  3. Confirm that claude_code.interaction contains claude_code.llm_request and claude_code.tool child spans.
  4. Confirm that model, token, duration, status, and tool fields are present.
  5. If content was enabled, verify that it matches the selected evidence policy.

An OTLP 200 response means Provon accepted and queued the payload. Trace summaries can appear asynchronously.

Optional Logs And Metrics#

Enable logs only when you need Claude Code events such as prompts, tool decisions, API requests, or API errors as independent log records:

bash
export OTEL_LOGS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_LOGS_ENDPOINT="$PROVON_OTEL_URL/logs"

Enable metrics only when you need Claude Code session, token, cost, code activity, or tool metrics outside the trace views:

bash
export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="$PROVON_OTEL_URL/metrics"

These signals are queried through the Telemetry Read API. They are not prerequisites for Traces, Conversations, Rules, or Findings.

Distributed Trace Context#

When tracing is active, Claude Code passes a W3C TRACEPARENT value to Bash and PowerShell subprocesses. Instrumented commands can use it to attach their spans below the active Claude Code tool span.

Claude Code does not pass the general OTEL_* exporter variables to Bash tools, hooks, MCP servers, or language servers. Configure those processes separately when they must export their own telemetry. This prevents the Provon API key and exporter destination from being inherited by every agent-launched process.

For Agent SDK and non-interactive claude -p sessions, Claude Code can accept inbound TRACEPARENT and TRACESTATE, allowing its interaction span to join a caller's distributed trace.

Organization-Wide Configuration#

Administrators can place telemetry environment variables in Claude Code managed settings to lock the exporter type, endpoint, protocol, and credentials for all users. Managed OTLP settings take precedence over conflicting developer values.

Distribute the project API key through the organization's approved secret and device-management system. Do not commit it to a repository-level Claude Code settings file.

See the Claude Code administrator configuration for precedence and destination-locking behavior.

Local And Self-Hosted Provon#

For the local Node runtime, change only the signal base:

bash
export PROVON_OTEL_URL="http://127.0.0.1:3000/v1"

The trace endpoint then resolves to http://127.0.0.1:3000/v1/traces.

For another self-hosted deployment, use its public OTLP/HTTP signal base.

Troubleshooting#

No Trace Arrives#

  • Set both CLAUDE_CODE_ENABLE_TELEMETRY=1 and CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1.
  • Set OTEL_TRACES_EXPORTER=otlp.
  • Confirm that the trace endpoint ends in exactly /v1/traces.
  • Use OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf.
  • Restart Claude Code after changing its environment.
  • Run claude --debug and inspect OTel export errors.

Provon Returns 401 Or 403#

  • Confirm that OTEL_EXPORTER_OTLP_HEADERS expands to Authorization=Bearer <key>.
  • Confirm that the key belongs to the intended project.
  • Confirm that the key has telemetry:ingest.
  • Do not use an Anthropic API key as the Provon credential.

Trace Content Is Redacted#

Redaction is the default. Enable OTEL_LOG_USER_PROMPTS or OTEL_LOG_TOOL_DETAILS only for the evidence your diagnostic policy requires. Use transcript sync when you need a controlled backfill from persisted session files.

Diagnosis Is Weak#

Inspect conversation identity, prompt evidence, model spans, tool spans, errors, recovery, and terminal outcome against Diagnosis-ready tracing. Native protocol support does not guarantee that every release emits complete diagnostic evidence.

Upstream Reference#