Skip to content

Connect Codex To Provon

Codex has native OpenTelemetry support. Send its traces to Provon to inspect coding-agent sessions and run conversation diagnosis without a wrapper.

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

Use Agent transcript sync to backfill existing sessions from ~/.codex/sessions/ or when the installed Codex version does not support trace export.

Choose Signals#

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

Signal Recommendation Use in Provon
Traces Required Trace explorer, conversations, diagnostic Rules, and Findings
Logs Optional Independent event search through the Telemetry Read API
Metrics Optional Independent aggregate usage and latency queries

Provon diagnostics build conversation evidence from spans. Codex logs and metrics do not enrich that span trajectory automatically. Enabling them by default creates additional ingest and storage without improving trace diagnosis.

The recommended configuration therefore exports traces only.

Prerequisites#

  • A Provon project.
  • A project API key with telemetry:ingest.
  • A current Codex CLI release whose configuration reference includes otel.trace_exporter.
  • Network access from Codex to the Provon OTLP endpoint.

Check the installed version:

bash
codex --version

Configure Trace Export#

Codex telemetry routing belongs in the user-level ~/.codex/config.toml. Codex ignores otel settings in project-local .codex/config.toml files.

Merge this block into ~/.codex/config.toml:

toml
[otel]
environment = "development"
exporter = "none"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "https://otel.provon.dev/v1/traces"
protocol = "binary"
headers = { Authorization = "Bearer <PROVON_API_KEY>" }

Replace <PROVON_API_KEY> with a project API key. protocol = "binary" selects OTLP protobuf over HTTP. Provon does not expose OTLP/gRPC.

The endpoint is a complete signal URL. Do not append another /v1.

This configuration does not route Codex metrics to Provon. Codex's separate built-in analytics setting is outside this integration and remains unchanged.

Protect the user configuration after adding the key:

bash
chmod 600 ~/.codex/config.toml

Keep The Key Out Of Codex Configuration#

Codex OTel exporter headers are static configuration. Do not assume that Authorization = "Bearer ${PROVON_API_KEY}" will expand: affected Codex versions send the placeholder literally.

When the project key must not be stored in config.toml, send Codex traces to a local OpenTelemetry Collector without authentication. Let the Collector read PROVON_API_KEY from its secret environment, add the Bearer header, and forward traces to Provon. See OpenTelemetry Collector setup.

Verify#

Restart Codex, run one prompt that causes a model request and a tool call, and exit normally so the batch exporter can flush:

bash
codex

Then:

  1. Open the same Provon project.
  2. Open Traces and select the latest Codex trace.
  3. Confirm that it contains model and tool child spans.
  4. Confirm that conversation identity remains stable across the session.
  5. Inspect model, usage, tool, error, and terminal outcome evidence.

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

Optional Logs And Metrics#

Enable Codex logs only when you need to query structured audit events such as API requests, tool decisions, and tool results independently of traces. Remove exporter = "none" and add:

toml
[otel.exporter.otlp-http]
endpoint = "https://otel.provon.dev/v1/logs"
protocol = "binary"
headers = { Authorization = "Bearer <PROVON_API_KEY>" }

Enable Codex metrics only when you need aggregate counters or histograms outside the trace views. Add:

toml
[otel.metrics_exporter.otlp-http]
endpoint = "https://otel.provon.dev/v1/metrics"
protocol = "binary"
headers = { Authorization = "Bearer <PROVON_API_KEY>" }

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

Privacy#

Keep log_user_prompt = false unless policy explicitly permits prompt storage. Even when prompts are redacted, paths, tool metadata, errors, and output snippets can contain sensitive information.

Use a narrowly scoped project key, apply an appropriate retention policy, and review one representative trace before an organization-wide rollout.

Do not enable native OTel and transcript sync for the same live session without a reason. They can project the same Codex activity as duplicate evidence.

Local And Self-Hosted Provon#

For the local Node runtime, use:

toml
[otel]
environment = "development"
exporter = "none"
log_user_prompt = false

[otel.trace_exporter.otlp-http]
endpoint = "http://127.0.0.1:3000/v1/traces"
protocol = "binary"
headers = { Authorization = "Bearer <PROVON_API_KEY>" }

For another self-hosted deployment, use its public OTLP/HTTP trace URL.

Troubleshooting#

Codex Rejects The Configuration#

Update Codex and confirm that its configuration reference includes otel.trace_exporter. Use transcript sync when an update is not possible.

Provon Returns 401 Or 403#

  • Replace the placeholder with the actual project key.
  • Include the Bearer prefix.
  • Confirm that the key belongs to the intended project.
  • Confirm that it has telemetry:ingest.

No Trace Arrives#

  • Exit Codex normally and allow the exporter to flush.
  • Check that the endpoint ends in exactly /v1/traces.
  • Use otlp-http, not otlp-grpc.
  • Confirm that Codex network policy permits the Provon endpoint.
  • Route through an approved Collector when direct egress is restricted.

Diagnosis Is Weak#

Protocol compatibility does not guarantee complete diagnostic evidence. Inspect conversation identity, model attributes, tool spans, errors, recovery, and terminal outcome against Diagnosis-ready tracing. Use transcript sync when the persisted session contains evidence that the native exporter does not emit.

Upstream References#