> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnia-voice.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Observability

> Traffic, latency, errors, and per-request detail for your usage.

The dashboard's **Observability** page shows how your gateway usage is behaving:
health, throughput, and speed, separate from billing (which lives under
[Usage](/billing/usage)). It's built to answer operational questions: Is my
traffic healthy? What's slow? Why are requests failing? How close am I to a rate
limit?

<Note>
  Observability is **dashboard-only**. There is no observability API; everything
  described here is viewed in the dashboard, not pulled programmatically.
</Note>

## Content-free by design

Omnia captures the **shape** of each request (timing, token counts, the names of
tools called, and status) but **never** your prompts or the model's responses.
Omnia is a gateway, not a data product. This applies everywhere in
observability, including the per-request detail view.

There are exactly two exceptions, both explicit and yours to make:
[response caching](/billing/caching) (retains responses so identical repeats
serve at a discount) and [request logging](/reference/request-logging)
(retains full conversations so you can browse, export, and curate them into
fine-tuning datasets). Both are opt-in workspace settings, off by default;
nothing is retained while they're off.

<Warning>
  Because telemetry is content-free, observability can't help you debug the
  *content* of a prompt or completion; it can only tell you about the request's
  timing, token counts, tool names, and status. Log prompt/response content on your
  own side if you need it.
</Warning>

## Headline stats

At the top of the page, the headline stats summarize health at a glance over the
selected window:

<CardGroup cols={2}>
  <Card title="Success rate" icon="circle-check">
    Share of requests that succeeded.
  </Card>

  <Card title="Requests" icon="chart-column">
    Total request volume over the window.
  </Card>

  <Card title="Latency p90" icon="gauge-high">
    End-to-end latency at the 90th percentile.
  </Card>

  <Card title="TTFT p90" icon="stopwatch">
    Time to first token at the 90th percentile.
  </Card>

  <Card title="Output speed" icon="bolt">
    Generation throughput in tokens per second.
  </Card>

  <Card title="Errors" icon="triangle-exclamation">
    Count of failed requests over the window.
  </Card>

  <Card title="Avg tokens / request" icon="calculator">
    Average token count per request.
  </Card>

  <Card title="Total tokens" icon="coins">
    Total tokens processed over the window.
  </Card>
</CardGroup>

## Charts

Time-series charts render over windows from **15 minutes to 90 days**, so you can
zoom from a live incident out to long-term trends:

* **Requests**: volume over time.
* **Errors**: failed requests over time.
* **Latency**: p50 / p90 / p99 percentiles.
* **TTFT**: time to first token.
* **Tokens**: token volume over time.
* **Output speed**: generation throughput in tokens per second.

## Errors by cause

When requests fail, the **Errors by cause** breakdown shows *why*, grouping
failures into categories (**rate limits**, **timeouts**, and **upstream
errors**) so you can act on the actual cause instead of just seeing an aggregate
error rate. Map these categories back to the specific status codes in
[Errors](/reference/errors): rate limits are `429`, timeouts are `408`, and
upstream errors are `502`.

## Per-model breakdown

A per-model table breaks the same metrics down by model, so you can spot which
model is slow, erroring, or driving your token volume, rather than reading a
blended average across all of them.

## Per-key breakdown

The same table exists per **API key**: which app, team, or environment is
driving traffic, errors, and cache savings. Key names come from your key list;
a key deleted since the traffic ran still shows (as "deleted key") so history
never loses attribution.

## Request labels: tags and trace ids

Label any request with two optional headers. No SDK changes, works from any
OpenAI client via `extra_headers`:

```bash theme={null}
curl https://gateway.omnia-voice.com/v1/chat/completions \
  -H "Authorization: Bearer $OMNIA_API_KEY" \
  -H "X-Omnia-Tag: checkout-bot" \
  -H "X-Omnia-Trace-Id: run_42" \
  ...
```

* **`X-Omnia-Tag`**: a short label (letters, digits, `_ : . -`, max 64
  chars; lowercased). Tagged traffic gets its own **Per-tag usage** table, tag
  chips in the request log, and a tag filter: segment by feature, customer,
  or environment.
* **`X-Omnia-Trace-Id`**: group the steps of a multi-request agent run; shown
  in the request detail.

These are labels, not content: invalid values are silently dropped, and
neither header is ever forwarded upstream. Your SDK's
`User-Agent` is also recorded (truncated) so you can spot which client
version is producing errors.

For traffic you never tagged, opt-in [request logging](/reference/request-logging)
adds auto-detected [segments](/concepts/segments), grouping by system-prompt
family, retroactively, with zero setup. Tags stay the deliberate override, and
the two compose.

## Finish reasons

A **Finish reasons** card breaks down how responses ended over the window:
`stop` (natural), `tool_calls`, and, highlighted amber, `length`, meaning
the response was **truncated by `max_tokens`**. A rising `length` count is the
classic silent failure: responses look successful but are cut off mid-thought.
Raise `max_tokens` or tighten prompts when you see it.

## Alerts

Get notified instead of finding out later: **Settings → Workspace → Alerts**
(owner/admin):

| Alert               | Fires when                                                          |
| ------------------- | ------------------------------------------------------------------- |
| Error rate spike    | errors exceed your threshold (default 10%) over the last 15 minutes |
| Latency degradation | latency p90 exceeds your threshold (default 30 s)                   |
| Low balance         | available balance drops below your threshold (default \$5)          |

Checks run every 5 minutes; each alert kind notifies **at most once per
hour**. Error/latency alerts require a minimum number of requests in the
window (default 20) so a single failed request never pages you. Notifications
go to the workspace owner's email and, optionally, an HTTPS **webhook** that
receives `{kind, value, threshold, detail, workspace, firedAt}`.

## Request log

The request log lists individual requests. Click any request to open its full,
content-free detail:

<AccordionGroup>
  <Accordion title="Timing" icon="stopwatch">
    Total latency, the **provider-vs-gateway latency split** (how much time was
    spent at the provider versus in the gateway), TTFT, and output speed.
  </Accordion>

  <Accordion title="Tokens" icon="coins">
    Token counts for the request.
  </Accordion>

  <Accordion title="Tool names" icon="wrench">
    The names of any tools the request called. Names only, never arguments or
    results.
  </Accordion>

  <Accordion title="Rate-limit headroom" icon="gauge">
    How close the request ran to the model's rate limits; see
    [Rate limits](/reference/rate-limits) for how to act on this.
  </Accordion>

  <Accordion title="Status" icon="signal">
    The request's outcome status.
  </Accordion>

  <Accordion title="Fallback" icon="shuffle">
    Whether the request was served by one of your
    [fallback models](/inference/chat#fallback-models), and which model it
    fell back from. Fallback-served requests also show a shuffle icon in the
    request list.
  </Accordion>
</AccordionGroup>

<Note>
  The request log is content-free and does **not** show the provider's request id
  to you. If you need to reference a specific upstream failure with support, use
  the request id included in the `502` error `message` (see
  [Errors](/reference/errors)).
</Note>

## Retention

You choose how long telemetry is retained, from **7 up to 90 days**. Data older
than your configured retention window is automatically deleted.

## Dedicated endpoints

Each [dedicated endpoint](/dedicated/overview) has its **own** observability page.
It shows the same traffic and latency charts described here, and adds
**capacity and replica metrics** so you can see how your reserved capacity is
holding up under load.