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 whe

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

Decision guide#

Requirement Start with
Route model calls and enforce policy through Provon AI Gateway
Keep the existing model-provider path OpenTelemetry
Capture live or backfill Claude, Codex, OpenCode, dsh, Cursor, or Pi sessions 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 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.

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.
  • 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.

Supported tools: Claude, Codex, OpenCode, dsh, Cursor, and Pi.

bash
# Live: install hooks for all detected tools
provon ingest hooks install

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

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.

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.