OpenTelemetry

Opt-in OTLP export of traces, metrics, and logs to your own collector or backend.

shunt can export traces, metrics, and logs over OTLP/HTTP to your own OpenTelemetry Collector (or any OTLP-compatible backend). It is opt-in and off by default — with no [otel] section, nothing leaves the machine — and runs independently of Sentry, so you can enable either or both.

Enable it

One key turns it on — point it at your Collector’s OTLP/HTTP receiver:

[otel]
endpoint = "http://localhost:4318"   # OTLP/HTTP base URL; shunt appends /v1/{traces,metrics,logs}

Everything else has a sensible default:

[otel]
endpoint = "http://localhost:4318"
service_name = "shunt"     # (default) service.name resource attribute
environment = "prod"       # optional deployment.environment.name
sample_ratio = 1.0         # (default) head-based trace sampling, 0.0–1.0
traces = true              # (default) export request spans
metrics = true             # (default) export usage metrics
logs = true                # (default) export log events (stderr logs unaffected)
include_session_id = false # (default) keep the client session id off spans

[otel.headers]             # optional per-request headers, e.g. a hosted-collector token
authorization = "Bearer <token>"

Setting endpoint = "" (e.g. SHUNT_OTEL__ENDPOINT="") disables export again without deleting the section. An invalid endpoint, a non-http(s) URL, or an out-of-range sample_ratio is a startup error, so a typo can’t silently drop every export.

The three signals

Signal	What’s exported	Notes
Traces	The per-request `proxy_request` span	Head-based sampling via `sample_ratio`. Low-cardinality; no request/response bodies.
Metrics	The low-cardinality series listed below	The same series shunt sends to Sentry when `[sentry] metrics = true`.
Logs	shunt’s `tracing` log events, bridged to OTLP	The stderr logs are unaffected.

Each signal toggles independently via traces / metrics / logs.

Metric series

Series	Type	Attributes	Meaning
`shunt.requests`	Counter	`provider`, `model`, `http.response.status_code`	Proxied inference requests.
`shunt.latency`	Histogram (ms)	`provider`, `model`, `http.response.status_code`	Header latency for streams; full latency otherwise.
`shunt.ttft`	Histogram (ms)	`provider`, `model`	Request start to the first SSE body chunk.
`shunt.stream_outcome`	Counter	`provider`, `model`, `outcome`	One final SSE result: `completed`, `error_event`, `upstream_cut`, or `client_disconnect`.
`shunt.tokens`	Counter	`provider`, `model`, `kind`	Last reported streaming token usage (`input`, `output`, `cache_read`, `cache_creation`). Non-streaming usage is not recorded.
`shunt.codex_continuation`	Counter	`provider`, `outcome`	Codex WebSocket continuation hit or fallback.
`shunt.codex_client_events`	Counter	`event`	Codex CLI analytics events by sanitized event name; payloads and properties are discarded.
`shunt.upstream_retries`	Counter	`provider`, `reason`	Bounded transient upstream retries.
`shunt.failover`	Counter	`provider`, `state`	Ordered-upstream failover transitions: `attempted`, `advanced`, or `exhausted`.
`shunt.pool.quota_utilization`	Gauge	`provider`, `window`	Minimum utilization across enabled, observed, non-expired quota values for `5h`, `7d`, or `7d_oi`.
`shunt.pool.rotations`	Counter	`provider`, `reason`	Moves off an account and requests that exhaust the pool.

Privacy

shunt never exports request/response bodies, headers, or credentials in metrics and traces.

Metrics and traces stay low-cardinality and body-free. With OTLP trace export, the request span’s client session id is sent to the collector only when include_session_id = true (default off), and only while trace export is active. The same rule governs Sentry trace export ([sentry] traces_sample_rate / include_session_id); with no span export active at all, the id stays on the local request span as before.
Logs mirror shunt’s own diagnostic events as written, so — like the stderr logs — they can include request-derived fields (an upstream error body, an authenticated client id). For strictly body-free export, set logs = false and keep metrics/traces.

The exported resource advertises service.*, telemetry.sdk.*, and — when environment is set — deployment.environment.name; no host or process detector runs, so the machine’s hostname is not attached, plus whatever you put in the standard OTEL_RESOURCE_ATTRIBUTES.

Standard `OTEL_` env vars

endpoint and service_name come from this config and take precedence over OTEL_EXPORTER_OTLP_ENDPOINT / OTEL_SERVICE_NAME.
The standard OTEL_EXPORTER_OTLP_HEADERS and OTEL_RESOURCE_ATTRIBUTES are still merged in, on top of [otel.headers] and the built-in resource attributes.

See the [otel] configuration reference for every key.