Agent insights troubleshooting

Overview

Agent insights can show less than you expect: an empty tab, a session with one part missing, or an agent dashboard with empty charts. Each problem has its own causes.

An empty Agent insights tab

An Agent insights tab that shows no timeline displays a message in its place. Each of the following sections covers one message, its causes, and the fix.

A message replaces the whole timeline. If the timeline renders but one part of it is empty, see Missing parts of a session.

Access denied

Only project admins can read the Agent insights data for a session. Members with the Read or Write role can open the tab, but every request for session data is refused.

Ask a project admin to change your role to Admin in your project settings. A share link doesn't give access to other roles. Only project admins and, if you allow it, LiveKit support can open it.

No observability data available

LiveKit Cloud has no traces or logs for this session. Either recording was off for the session, or the data never reached LiveKit Cloud. When the project setting is off, the message includes an Enable observability button.

Recording was off

Two settings turn off recording, so rule out both:

The project setting is off. Open Observability settings and confirm Agent observability is enabled. Enabling it applies to new sessions only. Sessions that ran while it was off stay empty.
The session opted out. An agent that calls session.start(agent, record=False) records nothing, even when the project setting is on. Check your agent code for a record argument. See Session recording options.

In both cases, an agent that omits record makes no upload attempt and logs nothing. An agent that passes record=True or an options object while the project setting is off has its upload rejected, and logs this once for the session:

LiveKit Cloud data recording is disabled for this project; skipping telemetry and recording uploads for this session

Recording is decided when the session starts

session.start() configures recording once. Turning the project setting on during a call has no effect on that call.

Two less common cases also record nothing:

A second session in one job. When a job runs more than one AgentSession, only the first is recorded. See Rules and limits.
A self-hosted media server. Agent observability needs LiveKit Cloud media servers. It works for a self-hosted agent that connects to LiveKit Cloud, but not for a self-hosted media server. See Availability.

The data didn't arrive

If recording was on, work through the following in order:

Check whether the session has ended. Transcripts and audio upload after the session ends. A session that's still running has no transcript and no audio yet, but traces and logs should already be there.
Check the Agents SDK version. Agent observability needs livekit-agents 1.3.0 or higher (Python) or @livekit/agents 1.0.18 or higher (Node.js). Older versions send nothing.
Look for upload failures in your own logs. The SDK logs failed to upload the session report to LiveKit Cloud (Python) or Failed to upload session report (Node.js) when an upload fails. It reports OpenTelemetry export errors on the same channel. Either one means the data never left the agent. Save those log lines and contact support with the session ID.
Confirm the agent reached session.start(). A job that crashes during the entrypoint uploads its buffered logs, but it produces no traces, transcripts, or audio.
Check that traces and logs weren't turned off. The tab needs traces or logs to render a timeline. With record={"traces": False, "logs": False}, the tab reports no data even when audio and transcripts uploaded.
Check whether OpenTelemetry is disabled in your environment. Agent insights is built on OpenTelemetry. In Python, setting OTEL_SDK_DISABLED=true in the agent's environment stops all traces and logs, and the session reports no data and no error. Remove it, then start a new session.
Check how your agent sets up its own tracing. You can export traces to another backend, but the Agents SDK must still be able to add its own exporter. In Node.js, a tracer provider registered without registerSpanProcessor turns off tracing to LiveKit Cloud and logs a warning. To send spans to both, see OpenTelemetry traces.

Agent insights expired

By default, agent observability data is deleted 30 days after a session ends. You can't restore an expired session. Sharing a session with LiveKit support doesn't extend it either.

To save one session before it expires, select Download data. The download is a ZIP archive of everything the session recorded. See Download a session.

To keep every session, write the data somewhere you control while sessions run: collect it in your agent, export traces to your own backend, or record audio with LiveKit Egress. All three write to storage you control, so the retention window doesn't apply.

We couldn't find this room session

LiveKit Cloud can't find this session ID in the project you're viewing. Check that you're in the right project and that the ID is correct. The session may also have expired: see Agent insights expired.

Missing parts of a session

When the timeline renders but one part of it is empty, match the gap to a cause:

What's missing	Likely cause
The transcript	`record={"transcript": False}`, or the session hasn't ended yet. With a realtime model and no separate STT plugin, transcripts can arrive late. See Delayed transcription.
The audio recording, with the transcript and traces present	The agent couldn't read the recording file when it built the session report, so the report uploaded without the audio. Starting with `livekit-agents` 1.7.0, the agent logs `failed to read audio recording for session report upload` with the file path.
The audio recording, with nothing else either	`record={"audio": False}`, or a text-only session. Audio always uploads after the session ends.
The end of an agent reply, in both the audio and the transcript	Expected when the user interrupts. Playback stops early, and the transcript for that turn keeps only the text that played.
Traces and metrics	`record={"traces": False}`.
Logs	`record={"logs": False}`, or your log level excludes them. LiveKit Cloud collects whatever the agent server emits, at `info` and higher by default. See Log levels.
Background audio	Expected. A background audio player publishes its own track and bypasses the session audio output, so the recorder never sees it.
Server-level events, such as crashes and dispatch errors	Expected. Session logs only cover activity inside a session. Set up a log drain to collect the rest.
Speech-to-text timing as its own span	Expected. Speech-to-text emits no span. Transcription timing is reported on `user_turn` as `lk.transcription_delay`. See Span reference.

Granular options apply at session start only

A record object takes effect when you pass it to session.start(). You can't change recording after the session starts, so a category is collected, or not, for the whole session. See Session recording options.

Gaps in the agent dashboards

Most charts on the Agents page come from session traces. A project with agent observability turned off still lists each agent and the number of sessions it served, and an agent page still shows its connection latency, uptime, and average load. The other charts are replaced with Observability is disabled for this project.

Two other gaps appear when LiveKit can't tell which agent produced the telemetry:

An Unattributed row in the Agents table. These are sessions that aren't attributed to an agent. Project totals count them, but they don't appear on any individual agent's page.
An agent with sessions but empty charts. The session count comes from job data, which is always attributed. The charts come from spans, which include the agent ID only on newer SDK versions.

Both usually indicate that the agent is running an older SDK version. Update to livekit-agents 1.6.8 (Python) or @livekit/agents 1.6.1 (Node.js) or later, then redeploy. These releases added the agent ID to reported spans and logs.

A self-hosted agent that runs without an agent name also lands in the Unattributed row. Give it a name to list it separately.

Getting help

If a session still looks wrong after working through this page, share it with LiveKit support. An admin can create a link that gives support access to the timeline, transcripts, traces, logs, and audio for that one session. See Sharing sessions with LiveKit support.

Ask questions and share what you're building in the LiveKit community forum . Direct email support from the LiveKit team is available to projects on the Ship plan or higher. To compare plans and the support each one includes, see the pricing page.

Additional resources

Agent insights

View transcripts, traces, logs, metrics, and audio for each session.

Data hooks

Collect session data in your own agent, independent of LiveKit Cloud.

OpenTelemetry traces

Send session traces to any OpenTelemetry-compatible backend.

Log drains

Forward runtime logs to external services for server-level visibility.