Choose A Capture Path
Provon can capture agent evidence through the AI Gateway, OpenTelemetry, or persisted agent transcripts. Choose one primary path, then combine paths only when a diagnosis needs mor
Decision Guide#
| Requirement | Start with |
|---|---|
| Route model calls and enforce policy through Provon | AI Gateway |
| Keep the existing model-provider path | OpenTelemetry |
| Analyze existing Claude Code, Codex, or Pi sessions | Agent transcript sync |
| Capture model calls plus application, tool, and workflow spans | Gateway and application OpenTelemetry |
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 surface;
- cloud, custom, and self-hosted 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.
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.
Agent Transcripts#
Use transcript sync for persisted Claude Code, Codex, and Pi sessions. The CLI detects supported formats, sanitizes content, projects sessions into canonical spans, and uploads them through the OTLP path.
Run a dry-run preview before uploading private transcripts.
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.
Verify The Choice#
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.
Continue with the Tracing quickstart or Gateway quickstart.