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

## Decision guide

| Requirement                                                                   | Start with                                   |
| ----------------------------------------------------------------------------- | -------------------------------------------- |
| Route model calls and enforce policy through Provon                           | [AI Gateway](../ai-gateway/quickstart.md)    |
| Keep the existing model-provider path                                         | [OpenTelemetry](../tracing/opentelemetry.md) |
| Capture live or backfill Claude, Codex, OpenCode, dsh, Cursor, or Pi sessions | [CLI ingest](../cli/ingest.md)               |
| 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`](https://github.com/provon/provon/tree/main/examples/gateway-endpoints)                   |
| TypeScript / Node.js agent         | AI Gateway or OTLP | [`examples/agent-observability-ts`](https://github.com/provon/provon/tree/main/examples/agent-observability-ts)         |
| Python agent with OpenTelemetry    | OTLP               | [`examples/agent-observability-python`](https://github.com/provon/provon/tree/main/examples/agent-observability-python) |
| Go agent with OpenTelemetry        | OTLP               | [`examples/agent-observability-go`](https://github.com/provon/provon/tree/main/examples/agent-observability-go)         |
| Claude Code, Codex, or Cursor user | CLI capture        | [`examples/diagnostics-findings`](https://github.com/provon/provon/tree/main/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](../ai-gateway/quickstart.md) and the runnable curl examples in
[`examples/gateway-endpoints`](https://github.com/provon/provon/tree/main/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](../tracing/opentelemetry.md) and the language-specific examples in
[`examples/agent-observability-*`](https://github.com/provon/provon/tree/main/examples).

## 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](../cli/ingest.md), [Install hooks CLI](../cli/install-hooks.md),
[CLI sync](../cli/sync.md), and the finding-producing example in
[`examples/diagnostics-findings`](https://github.com/provon/provon/tree/main/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](../tracing/quickstart.md) or
[Gateway quickstart](../ai-gateway/quickstart.md).