# 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 conversation diagnosis.

Use [Agent transcript sync](./agent-transcripts.md) 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](./telemetry-api.md). 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](https://code.claude.com/docs/en/monitoring-usage#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](./tracing-best-practices.md). Native protocol
support does not guarantee that every release emits complete diagnostic evidence.

## Upstream Reference

- [Claude Code monitoring and OpenTelemetry](https://code.claude.com/docs/en/monitoring-usage)

## Related Docs

- [OpenTelemetry setup](./opentelemetry.md)
- [OTLP/HTTP API](./otlp-api.md)
- [Agent transcript sync](./agent-transcripts.md)
- [Telemetry Read API](./telemetry-api.md)
- [Explore traces](./trace-explorer.md)