Skip to content

Choose a capture path

Provon can capture agent evidence through the AI Gateway, OpenTelemetry, or the CLI ingest path (live hooks and backfill sync). Choose one primary path, then combine paths only when a diagnosis needs more context.

View as Markdown Open the plain-text version of this page.
yes no OTLP already instrumented coding-agent transcripts only Model traffic through Provon AI Gateway Direct provider calls OpenTelemetry CLI ingest

All paths require a selected project and a key with telemetry:ingest; Gateway traffic also needs gateway:invoke.

Decision guide#

Requirement Start with
Route model calls and enforce policy through Provon AI Gateway
Keep the existing model-provider path OpenTelemetry
Capture local coding-agent sessions with live hooks or transcript backfill CLI ingest
Capture model calls plus application, tool, and workflow spans Gateway and application OpenTelemetry
Your stack Recommended path Runnable example
Python agent using OpenAI SDK AI Gateway examples/gateway-endpoints
TypeScript / Node.js agent AI Gateway or OTLP examples/agent-observability-ts
Python agent with OpenTelemetry OTLP examples/agent-observability-python
Go agent with OpenTelemetry OTLP examples/agent-observability-go
Claude Code, Codex, or Cursor user CLI capture examples/diagnostics-findings

All three paths produce project-scoped trace evidence. They differ in where instrumentation happens and how much of the complete agent execution they can observe.

AI Gateway#

Use the Gateway when Provon should own the model-call boundary. It provides:

  • an OpenAI-compatible request API;
  • cloud and custom model targets;
  • routing, retries, fallback, limits, and guardrails;
  • model attempt, token, cost, latency, and error evidence.

Gateway capture cannot infer application work that never crosses the model boundary. Add application spans when tool execution, retrieval, queues, or agent handoffs matter.

See the Gateway quickstart and the runnable curl examples in examples/gateway-endpoints.

OpenTelemetry#

Use OTLP when the application must call model providers directly or already has OpenTelemetry instrumentation. Provon accepts OTLP/HTTP traces, logs, and metrics and normalizes common GenAI semantics.

Instrument the complete user goal rather than only individual model requests. Preserve conversation identity and causal parent-child relationships so Provon can reconstruct the trajectory.

See OpenTelemetry setup and the language-specific examples in examples/agent-observability-*.

CLI capture#

Use the CLI ingest path when you work with coding agents that write local transcripts but do not expose an OTLP SDK. It offers two modes under a single provon ingest command group:

  • Live hooks — the CLI writes hook entries (or generates plugins) into each tool's config, so provon ingest trace <source> <hook> fires on session events and uploads the transcript as OTel spans while the agent is running. The hook command is non-blocking and returns immediately. Live capture uploads today for Claude, Codex, and Cursor. The generated OpenCode, dsh, and Pi plugins currently invoke a command this CLI build does not register, so their live hooks do not upload traces yet — read Current live-capture status before relying on those three.
  • Backfill sync — scan persisted transcript directories and upload them as traces. Use --once for a single pass or omit it to watch for changes continuously. Backfill works for Claude (~/.claude/projects), Codex (~/.codex/sessions), and Pi (~/.pi/agent/sessions). OpenCode and dsh do not persist transcripts into a directory that ingest sync scans.

provon ingest hooks install detects and offers to configure Claude, Codex, OpenCode, dsh, Cursor, and Pi — but detection/installation is not the same as live upload; see the status note above.

bash
# Live hooks (upload today for Claude, Codex, Cursor)
provon ingest hooks install

# Backfill: one-time upload with dry-run preview
provon ingest sync ~/.claude/projects --once --dry-run --print-sample

# Pi workaround: backfill persisted sessions instead of the (not-yet-aligned) live extension
provon ingest sync ~/.pi/agent/sessions --once

Both modes are idempotent: re-running hooks install updates existing entries, and sync skips unchanged files via content hashes.

See CLI ingest, Install hooks CLI, CLI sync, and the finding-producing example in examples/diagnostics-findings.

Avoid duplicate evidence#

When Gateway and application instrumentation observe the same model call, connect the spans through trace context or disable duplicate model-span export in one path. Duplicate independent spans can inflate token, cost, and failure counts.

Success Check#

Whichever path you choose, confirm that one representative run contains:

  • a stable trace and conversation identifier;
  • ordered model and tool activity;
  • the user goal and terminal answer;
  • provider, model, latency, usage, and error fields when available.

Troubleshooting#

Symptom Likely cause Fix
No trace after choosing Gateway Missing enabled model binding or invalid key Run provon gateway providers test; check Providers bindings
No trace after choosing OTLP Wrong protocol, endpoint suffix, or unflushed exporter Use OTLP/HTTP to /v1/traces; flush before exit; see Troubleshooting
No files found by CLI sync Directory has no supported transcript format Preview with --dry-run --print-sample; see Ingest sync
Duplicate model spans Gateway and app instrumentation overlap the same call Pass shared trace context, or disable model-span export on one path

Continue with the Tracing quickstart or Gateway quickstart.