# Observability Overview

> See the live state, per-segment traces, CDRs, MOS/jitter/loss, and per-tenant traffic for every call.

You can see everything a call does, in real time and after the call ends.
FirstByte Voice records each call's signalling, media quality, and agent
behaviour as they occur. It then folds this data into durable records. You can
query, chart, and alert on these records. You do not need to run a metrics
pipeline.

Every view uses the **same identifier**: the call's `sid`. The live-ops row, the
per-segment trace, the one-row CDR, the quality score, and the traffic tally all
use that one key. You can move from "what rings right now" to "why did this
specific call sound bad" without a manual match of IDs across systems.

## What you can see

  - **Live call state** — See every call that is up now. Each row shows who is on the call, which
    legs are attached (PSTN, SIP, browser, AI agent), and the call state
    (ringing, talking, held, queued). The engine pushes this data to your
    live-ops screens. Your screens do not poll.
  - **[Per-segment call traces](/modalities/voice/observability/call-traces)** — A trace has one row for each *segment* of a call. The AI-handled leg and
    the human-handled leg are separate rows. Each row has its own ring, talk,
    hold, queue, and wrap-up timings. Trace a call end-to-end across
    signalling, media, and the agent.
  - **Per-call CDRs** — The system writes one durable row for each completed call. The row has the
    start, answer, and clear timestamps, the duration, the standardized clear
    reason (Q.850), the codec, and the agent handler if there is one. Use this
    record for billing and reports.
  - **[Quality metrics](/modalities/voice/observability/mos-jitter-loss)** — The system records MOS, jitter, and packet loss for the media leg of every
    call. It computes the MOS score with the ITU-T E-model directly from the
    loss and jitter data. You can rank calls by real audio quality.
  - **[Per-tenant traffic](/modalities/voice/observability/dashboards)** — The engine attributes bytes and bandwidth to each workspace and each
    modality. It counts voice media per tenant and per call. You can see
    exactly which workspace causes the load.
  - **[Dashboards](/modalities/voice/observability/dashboards)** — Prebuilt production views use all of the data above. The views include
    all-calls reports, wallboards, agent timelines, VDN flow, and the traffic
    and bandwidth board.

## Live call state

While a call is up, the engine streams each state transition to your operations
screens. The transitions are: initiated, ringing, answered, held, resumed,
transferred, and cleared. The engine **pushes updates over the same low-latency
transport that carries the media**. Thus a wallboard shows the floor within a
tick, not on a polling interval.

Each live row shows the `sid`, the attached legs (a PSTN caller, a SIP
deskphone, a browser softphone, an AI agent), and the current state. When an AI
segment exists, the row also shows that an agent handles the call. The same
event stream later becomes the per-segment trace. Thus the live view and the
later query always agree.

> **TIP:**
> You can also fetch all live data on demand. Use the control-plane API to list
> the active calls when you need a point-in-time snapshot instead of a stream.
> See the SDK's call control surface under
> [Calls](/modalities/voice/api/calls).

## Per-segment traces vs. one-row CDRs

These are two different grains of the same call. Each grain is best for
different situations.

| You want to… | Reach for | Grain |
|---|---|---|
| Reconstruct what happened on a call: ring, talk, hold, queue, wrap-up, and the AI-vs-human split | [Call traces](/modalities/voice/observability/call-traces) | One row **per segment** |
| Bill, count, or report on completed calls (duration, clear reason, codec, agent-handled) | CDRs (below) | One row **per call** |
| Judge the audio quality of a call | [MOS / jitter / loss](/modalities/voice/observability/mos-jitter-loss) | One quality record **per call** |

A **call trace** records every lifecycle transition, grouped by `sid`. When a
call transfers from an AI agent to a human, the trace shows two segments: the
AI leg and the human leg. Each segment has its own timings. You can see how
long the caller spent with the bot before the warm handoff. You can also see
the timings of the human leg. Traces power agent timelines, wrap-up-to-ready
analysis, and VDN flow reports.

The system writes a **CDR** as one settled row when a call clears. The row has
the start, answer, and clear timestamps, the total duration, the Q.850 clear
reason mapped to a status, the negotiated codec, and the agent handler (if
any). Export this record for billing and long-horizon reports. The trace and
the CDR come from the same lifecycle events. Thus a CDR and its trace always
agree at their two grains. See
[Call lifecycle](/modalities/voice/transport-telephony/call-lifecycle) for the
transitions that build them.

## Quality: MOS, jitter, and loss

The media plane measures packet loss and jitter for the media leg of every
call. It uses the ITU-T G.107 E-model to compute an estimated **MOS** from
these measurements. The score is stored with the call's other records. Thus
"sort my calls by worst audio quality" is a simple query, not a forensic
exercise.

The media plane computes the score from the same loss and jitter counters that
it already tracks per call. Thus the score adds no cost at call time. The score
is available the moment the call clears. See
[MOS, jitter & packet loss](/modalities/voice/observability/mos-jitter-loss)
for how to read and use these numbers.

## Per-tenant traffic

The engine attributes bytes and bandwidth to the workspace that generated
them. The data is divided by modality. Voice media is counted per tenant and
per call. This data rolls up into a **Traffic & Bandwidth** view. From this one
view, you can see which workspace causes the load right now. You can also see
the trend of a tenant's voice traffic. This view shows load and cost for the
same fleet that the CDRs describe.

## Dashboards

Prebuilt production dashboards use the live state, traces, CDRs, quality, and
traffic data. The dashboards include: all-calls and call-detail reports, live
wallboards, agent timelines, VDN-flow and skill-drill views, and the traffic
board. See
[Production dashboards](/modalities/voice/observability/dashboards) to learn
which dashboards to watch. That page also tells you which dashboards are
polished and which are not complete yet.

> **NOTE:**
> Some dashboard tiles depend on features that you possibly did not enable. For
> example, the system fills the skill-queue view only after you route calls
> through an ACD skill. When a view has no data, it shows an empty panel. It does
> not invent numbers. An empty panel means "no traffic on that path". It does not
> mean an outage.

## When the summary isn't enough

The records above tell you *what* happened. Sometimes you need to know *why*:
a call sounds wrong, a transfer did not connect, or an agent talks over the
caller. Then use the lower-level tools:

  - **[SIP / RTP debugging](/modalities/voice/observability/sip-rtp-debugging)** — Inspect the telephony leg: SIP transactions, SDP negotiation, and the RTP
    media flow behind a specific `sid`.
  - **[Packet-level debugging](/modalities/voice/observability/packet-debugging)** — Examine the packets on the wire when the summaries and traces do not
    explain the problem.
  - **[Latency breakdown](/modalities/voice/observability/latency-breakdown)** — See the delay at each hop across the transport and the agent turn.
  - **[Barge-in debugging](/modalities/voice/observability/barge-in-debugging)** — Diagnose turn-taking problems: false barge-ins, missed interruptions, and
    an agent that talks over the caller.

## Related

  - **[Call lifecycle](/modalities/voice/transport-telephony/call-lifecycle)** — The lifecycle transitions that build every trace and CDR.
  - **[Sessions, calls, tracks & streams](/modalities/voice/concepts/sessions-calls-tracks-streams)** — The `sid` object model that connects every observability view.
