LiveKit metrics

Where livekit-agents 1.8 produces each metric, and every class and field it declares: what the wire's metrics models (pinecall/wire/metrics.py) are written against.

13 · 14 — where the metrics are produced#

Two independent channels, and we carry both.

The typed blocks. Every component (stt, tts, llm, vad, the interruption detector, the turn detector, the keyterm detector, a realtime session) emits metrics_collected on itself; AgentActivity subscribes to all of them (agent_activity.py:1044-1066) and forwards through _on_metrics_collected (:1967), which stamps speech_id on LLMMetrics and TTSMetrics from the speech-handle contextvar (:1971), feeds AgentSession.usage (:1981) and re-emits both metrics_collected (:1983) and session_usage_updated (:1984). EOUMetrics is emitted straight onto the session (:2699) and so never reaches the usage collector.

AgentSession.on("metrics_collected") is deprecated in 1.8 — subscribing logs a warning naming session_usage_updated and ChatMessage.metrics as the replacements (agent_session.py:725-731). The event still carries every block. The session subscribes to the components we built in providers/ instead, which is the same data with no warning, and takes the session's session_usage_updated for the rows. Two consequences, in session/session.py (_measured) and session/_livekit.py (end_of_utterance): an emitter's listeners are a set (rtc/event_emitter.py:15), so ours may run before livekit's own stamps speech_id on the block (:1971) — the write waits one loop tick; and EOUMetrics has no component to hear it on (:2699), so it is rebuilt from the user turn's own MetricsReport, the way livekit builds it (:2683-2697).

The per-turn latencies. New in 1.8: ChatMessage.metrics is a MetricsReport (agents/llm/chat_context.py:232,318), a total-false TypedDict — a field it could not measure is simply absent. The agent's report is assembled before the message exists (agent_activity.py:3568-3597) and handed to add_message(metrics=…) (:3620); the user's is built by _init_metrics_from_end_of_turn (:4768), attached at :2554, and on_user_turn_completed_delay is written into that same dict at :2615.

The timing, which is the whole reason the session's reading can be simple: a message reaches conversation_item_added (agent_session.py:2065) with its metrics already complete. The typed blocks arrive earlier — LLMMetrics when the stream closes, TTSMetrics per segment — so in the log metrics.llm precedes the turn.agent it belongs to, joined by speech_id.

The metrics, class by class#

Every class and every field the library declares, in declaration order. This table is the contract the wire's metrics models and the session's reading of them (session/_livekit.py) are built against. RealtimeModelMetrics.InputTokenDetails and .OutputTokenDetails are nested classes; the wire flattens their names to RealtimeInputTokenDetails / RealtimeOutputTokenDetails.

AgentSessionUsage (agents/metrics/usage.py:133) is one field, model_usage, a list of the five ModelUsage rows above; ModelUsageCollector (:137) sums them. call.summary carries that list whole.

18 — a streaming STT's STTMetrics is a usage meter, not a turn's block#

Seen on the first real voice call (room smoke-voice-1): 73 stored metrics.stt entries for a 42-second call, one every ~120 ms of speech, every field identical except timestamp and audio_duration. Read from the library, none of that is an anomaly.

A streamed STT emits STTMetrics from exactly two places, and neither is a turn. The first is STTStream._report_connection_acquired (agents/stt/stt.py:445-459), once per websocket, with zero usage and the only two numbers a stream ever measures about itself — acquire_time and connection_reused. The second is _metrics_monitor_task (agents/stt/stt.py:519-541), which turns every RECOGNITION_USAGE speech event into a block whose audio_duration is the incremental seconds of audio processed since the last report (stt.py:110-111) and whose duration is hard-coded 0.0 — as the field's own docstring says, "the request duration in seconds, 0.0 if the STT is streaming" (agents/metrics/base.py:54-55). The zero is the contract, not a plugin bug.

The cadence is the plugin's choice, and the two we ship differ by a factor of forty. Deepgram collects usage through a PeriodicCollector(callback=self._on_audio_duration_report, duration=5.0) (plugins/deepgram/stt.py:484-486, emitted at :801-809): one block per five seconds of audio. Soniox calls _report_processed_audio_duration(total_audio_proc_ms) for every frame it receives off the websocket (plugins/soniox/stt.py:604, the report itself at :312-326) — hence one block per partial, ~120 for a spoken sentence.

No STTMetrics can be joined to a turn. AgentActivity._on_metrics_collected stamps speech_id from the speech-handle contextvar onto LLMMetrics and TTSMetrics only (agents/voice/agent_activity.py:1969-1972), and STTMetrics declares no such field (agents/metrics/base.py:49-68). There is therefore no "the stt of this turn" to keep, and no last-one-of-the-turn to distinguish from the rest: the blocks are indistinguishable by construction.

The turn's STT numbers live elsewhere, and we already store them whole. transcription_delay and end_of_turn_delay ride the ChatMessage.metrics report (verdict 14) — the log writes them as turn.user.metrics and, rebuilt, as metrics.eou. And the call's STT total is not lost by dropping the ticks: livekit sums exactly these blocks into STTModelUsage.audio_duration (agents/metrics/usage.py:87-101, summed by ModelUsageCollector, :137), which call.summary carries whole and providers/prices.py bills from. On the smoke call the 73 ticks summed to the 42.48 s the summary row already carried.

What the session does with them is session/session.py _write_block: a streaming STT's tick with no acquire_time is written ephemeral, so the durable log keeps the total and not the ticks.