From 300479e91d5c1d17a8e5c796d99f87218f0a8c63 Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Wed, 1 Jul 2026 18:21:04 +0530 Subject: [PATCH 1/3] docs(observe): fix Voice observability Keep-exploring cards - Remove the 'Trace a LiveKit voice app' card: its target /docs/traceai/auto/livekit is not live on this branch, and we don't card non-live pages. - Fix invalid card icon: compass -> layer-group (compass is not in this branch's Card.astro icon map, so it rendered blank). - CardGroup down to cols=2 per the count % 3 rule. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/pages/docs/observe/concepts/voice-observability.mdx | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/src/pages/docs/observe/concepts/voice-observability.mdx b/src/pages/docs/observe/concepts/voice-observability.mdx index 747272cb..eb251a93 100644 --- a/src/pages/docs/observe/concepts/voice-observability.mdx +++ b/src/pages/docs/observe/concepts/voice-observability.mdx @@ -38,14 +38,11 @@ Voice failures are the ones you hear about from a customer, not a log: the agent ## Keep exploring - - - Auto-instrument a LiveKit voice agent through traceAI - + Score voice conversations for quality and safety - + How spans, traces, sessions, and users fit together From 26c3cdcc7b00dae010bf51cba8c2b5563ca0dbb6 Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Wed, 1 Jul 2026 18:48:07 +0530 Subject: [PATCH 2/3] docs(observe): one-read clarity pass on Voice observability - Split the run-on worked example into clean sentences; drop the captured-fields restatement the opener already covers. - Trim 'Why it matters' to the actual motivation; cut the decorative tricolon and the eval/alert/filter list already stated up top. - Link evals at its true first mention (the opener), not later. Co-Authored-By: Claude Opus 4.8 (1M context) --- src/pages/docs/observe/concepts/voice-observability.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/pages/docs/observe/concepts/voice-observability.mdx b/src/pages/docs/observe/concepts/voice-observability.mdx index eb251a93..f5a804fa 100644 --- a/src/pages/docs/observe/concepts/voice-observability.mdx +++ b/src/pages/docs/observe/concepts/voice-observability.mdx @@ -5,7 +5,7 @@ description: "Turning every voice call into a trace you can debug and score." ## A voice call is a trace -**Voice observability** captures each voice call as a [trace](/docs/observe/concepts/traces), the same tree of [spans](/docs/observe/concepts/spans) you get from a text app. One call becomes one trace: each back-and-forth turn is a span inside it, and the whole thing carries the transcript, the recording, and the call's duration, turn count, and cost. A spoken conversation lands in the same place as every other request, ready for the same evals, alerts, and filters. +**Voice observability** captures each voice call as a [trace](/docs/observe/concepts/traces), the same tree of [spans](/docs/observe/concepts/spans) you get from a text app. One call becomes one trace, and each back-and-forth turn is a span inside it. The call carries the transcript, the recording, and its duration, turn count, and cost. A spoken conversation lands in the same place as every other request, ready for the same [evals](/docs/observe/features/evals), alerts, and filters. A voice call reaches Observe by one of two paths: @@ -21,11 +21,11 @@ Either way you land on the same thing: one voice call you can open as a trace. B["LiveKit / Pipecat app"] -->|"traceAI emits spans"| T T --> D["Transcript · recording · turns · cost"]`} /> -Take a support line running on a Vapi assistant. Observe pulls each finished call in as its own trace: read it top to bottom and you follow the conversation turn by turn, with the transcript and recording sitting right on the call and its duration, turn count, and cost totalled up. When a caller reports the agent misheard their order number, you open that one call, jump to the turn where it happened, and play the audio back, instead of guessing from a dashboard. +Take a support line running on a Vapi assistant. Observe pulls each finished call in as its own trace, so you read it top to bottom and follow the conversation turn by turn. When a caller reports the agent misheard their order number, you open that one call, jump to the turn where it happened, and play the audio back, instead of guessing from a dashboard. ## When to use -Reach for voice observability when what you are debugging is a spoken conversation: a caller who got the wrong answer, an agent that ran long, a call that cost more than it should. It earns its place when you want those calls sitting alongside the rest of your traces, ready to score and monitor. +Reach for voice observability when what you are debugging is a spoken conversation: a caller who got the wrong answer, an agent that ran long, a call that cost more than it should. It also fits when you want those calls sitting alongside the rest of your traces, ready to score and monitor. When the grain is wrong, reach elsewhere: @@ -34,7 +34,7 @@ When the grain is wrong, reach elsewhere: ## Why it matters -Voice failures are the ones you hear about from a customer, not a log: the agent talked over the caller, misheard a number, or trailed off. A spoken call leaves nothing behind to inspect. Capturing it as a trace changes that. You get the transcript to read, the recording to play, and per-turn timing to see where it dragged, all on one call. And because it is just a trace, everything else works on it too: run [evals](/docs/observe/features/evals) on the conversation, set alerts when calls start failing, filter and export like anything else. +Voice failures are the ones you hear about from a customer, not a log. A spoken call normally leaves nothing behind to inspect; capturing it as a trace changes that, so a complaint becomes a call you can open, read, and replay instead of a guess. ## Keep exploring From 2eeb85234256abe10389e73735b5c084541daa28 Mon Sep 17 00:00:00 2001 From: Yash Mohan Date: Wed, 1 Jul 2026 18:53:02 +0530 Subject: [PATCH 3/3] docs(observe): add substantive depth to Voice observability concept - New 'Inside a voice call' section: a turn span breaks down into speech-to-text, the model call, and text-to-speech (grounded in the LiveKit/Pipecat auto-instrumentation), so a reader sees what a voice trace looks like inside, not just that a call is a trace. - New Mermaid of the call structure (replaces the two-paths plumbing diagram). - Two ingestion paths now a scannable table (managed Vapi/Retell vs LiveKit/Pipecat auto-instrumentation). - Cross-link to the observability model. Co-Authored-By: Claude Opus 4.8 (1M context) --- .../observe/concepts/voice-observability.mdx | 35 +++++++++++++------ 1 file changed, 25 insertions(+), 10 deletions(-) diff --git a/src/pages/docs/observe/concepts/voice-observability.mdx b/src/pages/docs/observe/concepts/voice-observability.mdx index f5a804fa..a2f2571e 100644 --- a/src/pages/docs/observe/concepts/voice-observability.mdx +++ b/src/pages/docs/observe/concepts/voice-observability.mdx @@ -7,19 +7,34 @@ description: "Turning every voice call into a trace you can debug and score." **Voice observability** captures each voice call as a [trace](/docs/observe/concepts/traces), the same tree of [spans](/docs/observe/concepts/spans) you get from a text app. One call becomes one trace, and each back-and-forth turn is a span inside it. The call carries the transcript, the recording, and its duration, turn count, and cost. A spoken conversation lands in the same place as every other request, ready for the same [evals](/docs/observe/features/evals), alerts, and filters. -A voice call reaches Observe by one of two paths: +## Inside a voice call -- **Managed ingestion**, for hosted providers like Vapi and Retell. Connect the provider once with its API key and assistant ID and switch observability on. Observe pulls the provider's call logs and writes each finished call in as a trace, with no SDK and no code on your side. -- **Auto-instrumentation**, for voice apps you build on LiveKit or Pipecat. Your app emits spans through [traceAI](/docs/observe/concepts/traceai), exactly like any other instrumented service. - -Either way you land on the same thing: one voice call you can open as a trace. +A turn is more than a single step. In an app you instrument on LiveKit or Pipecat, a turn's span breaks down into speech-to-text, the model call, and text-to-speech, so you can see exactly where a turn went wrong, not just that it did. Managed calls arrive at the turn level, and the transcript and recording sit on the call either way. |"Observe pulls call logs"| T["One voice call, as a trace"] - B["LiveKit / Pipecat app"] -->|"traceAI emits spans"| T - T --> D["Transcript · recording · turns · cost"]`} /> + accTitle: What a voice call looks like as a trace + accDescr: A voice call is one trace made of turn spans. In an instrumented app each turn breaks down into speech-to-text, the model call, and text-to-speech. The call carries the transcript, recording, turn count, and cost. + C["Voice call · one trace"] --> T1["Turn · span"] + C --> T2["Turn · span"] + T1 --> STT["speech to text"] + T1 --> LLM["model call"] + T1 --> TTS["text to speech"] + C --> M["Transcript · recording · turns · cost"]`} /> + +Because it is an ordinary trace, a voice call fits the same [observability model](/docs/observe/concepts/observability-model) as your text traces. + +## How a call reaches Observe + +A voice call reaches Observe by one of two paths. Whichever it takes, it lands as the same trace; what differs is who produces the spans. + +| Path | For | How spans are produced | What you write | +|---|---|---|---| +| **Managed ingestion** | Hosted agents on Vapi or Retell | Observe pulls the provider's call logs | No code: connect the provider and turn observability on | +| **Auto-instrumentation** | Apps built on LiveKit or Pipecat | Your app emits a span per turn through [traceAI](/docs/observe/concepts/traceai) | A few lines of traceAI setup | + +For the managed-ingestion setup, see [Voice observability](/docs/observe/features/voice). + +## Debugging a call Take a support line running on a Vapi assistant. Observe pulls each finished call in as its own trace, so you read it top to bottom and follow the conversation turn by turn. When a caller reports the agent misheard their order number, you open that one call, jump to the turn where it happened, and play the audio back, instead of guessing from a dashboard.