Inspect a request trace and reconcile cost
Use Logs and optional OpenTelemetry traces to explain routing, timing, tokens, and cost.
Purpose
Explain one Relay request from route resolution through terminal accounting. Use the request log as the canonical usage record.
Prerequisites
- Relay has completed at least one request.
- The selected Model has configured pricing if you need a cost value.
- You can open Logs.
Inspect the request
- Open Logs.
- Filter by result, characterization, Guardrail state, requester, or route when those filters are available.
- Select one request.
- Confirm the incoming target and route kind.
- Confirm the selected Provider and Model.
- Inspect candidate evaluation and fallback count.
- Read each reported timing stage.
- Compare estimated tokens and cost with actual terminal values.
Interpret the values
| Value | Meaning |
|---|---|
| Queue wait | Time under scheduler control before dispatch |
| Characterization | Reported classification time when characterization ran |
| Guardrails pre | Time spent before provider dispatch |
| Provider latency | Time spent in the selected upstream call |
| Guardrails post | Time spent after a non-streaming provider response |
| Total | Complete reported Relay duration |
| Estimated usage | Capacity reserved before dispatch |
| Actual usage | Provider-reported or resolved terminal usage |
| Cost | Configured price applied to resolved usage |
A configured price is an operator value. Relay does not automatically synchronize every provider price.
Check response metadata
Trusted callers can inspect safe X-Relay-* response headers for the selected route, wait, fallback count, token counts, and cost when those values are available. These headers do not contain prompts, responses, credentials, cookies, or API-key secrets.
Export a distributed trace
Set an OTLP/HTTP endpoint to enable OpenTelemetry export. Relay traces request context verification, route selection, scheduler wait and admission, database operations, provider HTTP time, and terminal persistence.
Do not enable SQL statement export unless you accept placeholder SQL text in the telemetry system. Relay excludes SQL bound values.
Expected result
The request log identifies the caller, routing decision, reported timing stages, terminal usage, and configured cost for one request.
Verification
The request log, response metadata, usage totals, and trace must identify the same selected Provider and Model. Actual input plus output tokens must equal actual total tokens when all values are available.
Recovery
- If actual usage is absent, inspect the provider response and adapter mapping.
- If cost is absent, configure Model pricing.
- If payloads are absent, check whether payload capture was enabled before the request. Operational metadata remains available when capture is off.