LiveKit docs › Test & Evaluate › Observability › Agent Insights --- # Agent insights > View audio recordings, transcripts, traces, logs, and metrics for your agent sessions in LiveKit Cloud. ## Overview LiveKit Cloud includes a built-in observability stack for voice agents. When you enable **Agent observability** for a project, LiveKit Cloud collects transcripts, traces, logs, and audio recordings for each session. The **Agent insights** tab on each session aligns them on a single timeline, so you can play back a call and see what the agent did at each point. [Video: LiveKit Agents Observability](https://www.youtube.com/watch?v=LAXpS14bzW4) ## Availability Agent observability is available on all LiveKit Cloud plans, and works for agents deployed to LiveKit Cloud and for self-hosted agents that connect to LiveKit Cloud media servers. It does not work with self-hosted media servers or entirely self-hosted deployments. For complete information on pricing, see the [LiveKit Cloud pricing page](https://livekit.com/pricing). To enable agent observability, ensure the following conditions are met: 1. The **Agent observability** feature is enabled within the **Observability settings** section in your [project settings](https://cloud.livekit.io/projects/p_/settings/observability). 2. Your agent uses the latest version of the LiveKit Agents SDK- Python SDK version 1.3.0 or higher - Node.js SDK version 1.0.18 or higher - Or the [LiveKit Agent Builder](https://docs.livekit.io/agents/start/builder.md) The project setting governs every session. To change what a single session collects, pass the `record` parameter to `AgentSession.start()`. See [Session recording options](https://docs.livekit.io/reference/agents/session-recording-options.md). ### Permissions Only project admins can read the Agent insights data for a session. To give a teammate access, change their role to Admin in your project settings. A [share link](#share-session-link) doesn't give access to other roles. Only project admins and, if you allow it, LiveKit support can open it. ## Where to find session data The data that agent observability collects appears at three levels in the LiveKit Cloud dashboard: - **Project:** open the [**Agents**](https://cloud.livekit.io/projects/p_/agents) page to see traffic, latency, and model usage across every agent in the project. - **Agent:** select an agent on the **Agents** page to see the same charts, scoped to that agent. An agent page also shows how the time in an average reply divides between pipeline stages, and charts for connection latency, uptime, and average load. - **Session:** open a session on the [**Sessions**](https://cloud.livekit.io/projects/p_/sessions) page and select the **Agent insights** tab to see the timeline for a single call. ### Agent insights compared to the other session views A session has several views, and they answer different questions. Switch between them from the session ID in the breadcrumb. | View | Answers | Needs agent observability | | **Session analytics** | How the connection performed: duration, participants, connection quality, bandwidth, publisher and subscriber media stats. | No | | **Session events** | What happened to the room: participants joining and leaving, tracks being published, and other room lifecycle events. | No | | **Agent insights** | What the agent did: transcripts, traces, logs, metrics, and audio. | Yes | **Session analytics** and **Session events** come from the LiveKit media servers, so they're present for any session and visible to every project role. **Agent insights** comes from telemetry your agent uploads, so it needs agent observability enabled and is limited to [project admins](#permissions). The data region for your project determines where these recordings, transcripts, and traces are stored. It's set when you create the project and can't be changed afterward. To keep agent observability data in the EU, select the EU data region at project creation. To learn more, see [Data residency](https://docs.livekit.io/testing/observability/data-residency.md). ## What the timeline includes The timeline for each agent session combines transcripts, traces, logs, audio clips, and the per-event metrics emitted by the LiveKit Agents SDK. ### Ingestion timing Different parts of a session arrive at different times: - **Traces and logs** stream to LiveKit Cloud while the session runs. Open a live session to see the spans and log lines that arrived so far, and reload the page to see newer ones. - **Transcripts and the audio recording** are held in the agent process and uploaded after the session ends, because both are assembled from the whole call. If a session that has ended still shows no data, see [Troubleshooting](https://docs.livekit.io/testing/observability/troubleshooting.md). The SDK flushes the remaining telemetry after your [`on_session_end`](https://docs.livekit.io/testing/observability/data.md#session-reports) callback returns, so a long callback delays the upload. The `session_end_timeout` agent server option bounds how long that callback can run. ### Transcripts Turn-by-turn transcripts for the user and agent. Tool calls and handoffs also appear on the timeline so you can correlate them with traces and logs. Select any of them to see the metadata and metrics in a side panel. ### Session traces and metrics Traces capture the execution flow of a session, broken into spans for every stage of the voice pipeline. Spans cover user and agent turns, STT-LLM-TTS pipeline steps, tool calls, and more. Each span includes metrics and metadata, such as token counts, durations, and speech identifiers, that you can inspect in a side panel when you select the span. For the full list of spans and what each one records, see [Session traces and metrics](https://docs.livekit.io/reference/agents/session-traces.md). ### Logs Runtime logs from the agent server are uploaded to LiveKit Cloud and available in the session timeline. LiveKit Cloud collects whatever your agent server emits, so the log level you configure for the agent server is also the level collected for observability. By default, this is `info` and higher. See [Log levels](https://docs.livekit.io/agents/server/options.md#log-levels) for details. These logs only cover activity within a session. Server-level events that happen outside of a session (such as crashes, startup failures, and dispatch errors) aren't captured here. To collect those, set up a [log drain](https://docs.livekit.io/deploy/agents/log-drains.md). ### Session metrics The **Metrics** tab summarizes the performance of one session: how the conversation flowed, how long each stage of the voice pipeline took, and what the session used in models, tokens, and speech. Tiles that need audio, such as **Interruptions** and **Speech usage**, don't appear for text-only sessions. ## Working with charts Charts in Agent insights are interactive, and what a selection does depends on where the chart is. The current drawer and filter state is encoded in the URL as query parameters, so copying the URL shares the exact view you're looking at. ### In a session timeline Charts on the **Metrics** tab are keyed to turns. Select a turn in **Agent turn latency**, or an outlier point in **Latency distribution**, and playback moves to that turn and marks it on the charts. Then switch to **Transcript**, **Traces**, or **Session logs** to see what happened at that point. Selecting a span or item in any of those tabs also marks its turn on the charts. ### In an agent dashboard Charts on the [Agents](https://cloud.livekit.io/projects/p_/agents) page drill down to sessions. Selecting part of a chart opens a drawer listing the sessions behind it. A latency chart ranks those sessions by their slowest turn for that stage. A count chart, such as interruption rate, lists only the sessions that recorded one. Drag across the x-axis of a time-series chart to select a window. **Zoom to selection** applies that window to the whole page, so every other chart rescales to match, and **View sessions** opens the sessions drawer for it. ### Compare agents side by side On the [Agents](https://cloud.livekit.io/projects/p_/agents) page, select two or more agents in the **Agents** table and select **Compare agents**. A drawer opens with the selected agents ranked slowest first, with sessions per bucket and E2E metrics. Charts in the drawer drill down to the selected agents only, and you can compare up to 25 agents at once. > ℹ️ **Stage averages overlap** > > Stages in the pipeline overlap in time, so the segments of a composition bar don't add up to the p50 or p95 beside them. Use the bars to compare agents against each other, and the percentiles to judge the absolute latency of one agent. ## Audio recordings Audio recordings are collected for each agent session and play back in the browser, in sync with the timeline. They're recorded in the agent process and uploaded to LiveKit Cloud after the session ends, along with the transcripts. Recordings include both the agent and the user audio, on separate channels. To save a recording, select **Download data** on the session. To learn more, see [Download a session](#download-data). ### Recording limitations The recorder taps the audio input and output of the agent session, which sets what it can capture: - If [noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation.md) is enabled, user audio is recorded after noise cancellation is applied. The recording reflects what the STT or realtime model heard. - Audio from a [background audio player](https://docs.livekit.io/agents/multimodality/audio/background-audio.md) is published as a separate track and doesn't pass through the session audio output, so it isn't in the recording. Audio you speak with `session.say()` is in the recording, so use it for content that must be captured, such as a disclosure. - When the user interrupts, playback stops early, so agent audio can end mid-sentence. The transcript for that turn keeps only the text that played. See [Missing parts of a session](https://docs.livekit.io/testing/observability/troubleshooting.md#missing-parts). ### Agent insights audio compared to LiveKit Egress Agent insights audio and [LiveKit Egress](https://docs.livekit.io/transport/media/ingress-egress/egress.md) are separate pipelines, and neither one populates the other. Agent insights audio is recorded by the agent and uploaded to LiveKit Cloud, where it's subject to the [retention window](#retention-window). It never reaches your own storage bucket. An Egress recording writes to your bucket, and it doesn't add audio to the Agent insights waveform or player. You can save one Agent insights recording at a time with **Download data**. Use Egress instead when you need every call delivered to your own storage, video as well as audio, or audio captured before noise cancellation. To learn more, see [Record audio and video](https://docs.livekit.io/testing/observability/recording.md). ### Download a session Within the dashboard, an admin can select **Download data** on a session to save it as a ZIP archive. This is how you keep one session past its [retention window](#retention-window). The archive holds one file per category the session recorded, named `__`: | File | Contents | | `traces.json` | The spans for the session, as OTLP JSON. | | `logs.json` | The runtime logs collected for the session, as OTLP JSON. | | `metrics.json` | The latency and usage metrics the SDK emits, such as `lk.agents.turn.llm_ttft` and `lk.agents.usage.tts_characters`, as OTLP JSON. | | `chat_history.json` | The transcript: each turn with its role, content, and metrics, plus handoffs and agent config updates. | | `audio.oga` | The recording, as OGG Opus, with the user and the agent on separate channels. | A category the session didn't record is absent from the archive, so a session that ran with `record={"audio": False}` has no audio file. ## Retention window By default, agent observability data is deleted 30 days after a session ends. After that, the session reports **Agent insights expired**. To keep a session for longer, select **Download data** on it before it expires. To keep every session, write the data somewhere you control while sessions run: see [Accessing data outside the dashboard](#programmatic-access). This window covers what LiveKit stores. Models you call through LiveKit Inference are [zero data retention](https://docs.livekit.io/agents/models/inference.md#zero-data-retention) on every plan, so model providers don't retain or train on the data you send them. ### PII redaction To remove personally identifiable information from session transcripts, audio, and telemetry before it's stored, enable [PII redaction](https://docs.livekit.io/testing/observability/pii-redaction.md) for your project. Redaction is bundled with agent observability at no additional cost and is off by default. ## Sharing sessions with LiveKit support You can share insights for a specific agent session with LiveKit support. When sharing is enabled, LiveKit support staff can access the session timeline, transcripts, traces, logs, and audio recordings to help troubleshoot issues. If you haven't already, work through [Troubleshooting](https://docs.livekit.io/testing/observability/troubleshooting.md) first. It covers the common causes of missing and incomplete session data. > ℹ️ **LiveKit support availability** > > LiveKit support is only available for projects on the **Ship** plan or higher. To learn more about the different plans, see the [pricing page](https://livekit.com/pricing). To enable or disable sharing with LiveKit support, follow these steps: 1. Sign in to the LiveKit Cloud dashboard and navigate to the [**Sessions**](https://cloud.livekit.io/projects/p_/sessions) page. 2. Select the session you want to share. 3. Select the **Agent insights** tab → select **Share**. 4. Select **Allow LiveKit support to access this page** to turn sharing with LiveKit support on or off. 5. Select **Copy link** to copy the share link to the clipboard. 6. Email the link to LiveKit support. The sharing link for a session remains active until the [retention period](#retention-window) ends. To stop sharing the session before then, you must disable it explicitly by repeating the previous steps. > ℹ️ **Sharing doesn't change the retention window** > > Sharing a session with LiveKit support doesn't extend the [retention window](#retention-window). The session data is deleted when the retention period ends and the sharing link expires. ## Additional resources - **[Troubleshooting](https://docs.livekit.io/testing/observability/troubleshooting.md)**: Diagnose an empty Agent insights tab or missing session data. - **[Data hooks](https://docs.livekit.io/testing/observability/data.md)**: Collect metrics locally, export traces via OpenTelemetry, and build custom integrations. - **[Log drains](https://docs.livekit.io/deploy/agents/log-drains.md)**: Forward runtime logs to external services for server-level visibility. - **[Logs](https://docs.livekit.io/deploy/agents/logs.md)**: View runtime and build logs with the CLI. - **[PII redaction](https://docs.livekit.io/testing/observability/pii-redaction.md)**: Redact personally identifiable information from stored agent observability data. - **[Session traces and metrics](https://docs.livekit.io/reference/agents/session-traces.md)**: Reference for the spans and latency stages reported for each session. - **[Session recording options](https://docs.livekit.io/reference/agents/session-recording-options.md)**: Reference for the `record` parameter on `AgentSession.start()`. --- This document was rendered at 2026-10-18T00:26:12.350Z. For the latest version of this document, see [https://docs.livekit.io/testing/observability/insights.md](https://docs.livekit.io/testing/observability/insights.md). To explore all LiveKit documentation, see [llms.txt](https://docs.livekit.io/llms.txt).