I have the following code. the usage_collector is always empty. why?

Thanks for reaching out, Sunil. I'm an AI assistant and I'm here to help. Give me a moment while I research this topic.

@session.on("metrics_collected") def _on_metrics_collected(mtrcs: metrics.AgentMetrics): global usage_collector logger.info("******************************* METRICS COLLECTED") logger.info(mtrcs.model_dump_json(indent=2)) usage_collector.collect(mtrcs) logger.info(f"******************************* SUMMARY AFTER COLLECT : {usage_collector.get_summary()}")

Hey there! Looking at your code snippet and the context, here are a few reasons why

usage_collector

might still be empty: • No Metrics Events Being Fired: The

usage_collector

fills up only when the

metrics_collected

event happens. If you’re not seeing any events fired, the collector will stay empty. This might be because the session hasn’t started yet, or none of the AI services (like STT, LLM, or TTS) are currently in use. • Session Not Active: Make sure you’ve started the session with

await session.start()

. Without an active session, no metrics will come through. • Event Handler Not Properly Registered: The event handler needs to be set up before the session kicks off. For example:

@session.on("metrics_collected")
def _on_metrics_collected(ev: MetricsCollectedEvent):
    usage_collector.collect(ev.metrics)

# Then later:
await session.start(...)

• Timing Issues: If you check

usage_collector.get_summary()

before using any AI services or before the session has processed interactions, it’ll naturally be empty. Here’s a quick checklist to help you troubleshoot: 1. Is your session active and started? 2. Are AI services being used during the session? 3. Is the event handler registered before starting the session? 4. Are metrics actually being generated and collected? If you’ve gone through these and it’s still not working, just let me know! I’m here to help you figure it out. Sources: Capturing metrics | LiveKit Docs | livekit-plugins/livekit-plugins-openai/livekit/plugins/openai/realtime/real...

sorry! forgot to add, the event is fired, event handler is invoked properly, json dump of AgentMetrics has data. it is just the usage_collector.collect which is not collecting and showing summary

Thanks so much for sharing those extra details! Based on what you’ve told me, here are a few reasons why

usage_collector.collect

might not be picking up data or showing a summary, even though

AgentMetrics

does have data: • Unrecognized Metric Types: The

UsageCollector.collect()

method works with specific metric types like

LLMMetrics

,

TTSMetrics

,

STTMetrics

, or

RealtimeModelMetrics

. So, if your

AgentMetrics

doesn’t fall into one of these categories, it might be getting skipped. • Incorrect Metrics Object Structure: The metrics object might be missing some expected properties (like

promptTokens

,

charactersCount

, or

audioDuration

) that the collector needs to process properly. • Summary Access Issues: Double-check that you’re grabbing the summary the right way using

usage_collector.get_summary()

. To help figure this out, you could try: 1. Verify Metrics Types: Take a look at the type of

AgentMetrics

objects you’re passing into

usage_collector.collect

and make sure they match one of the supported types (

LLMMetrics

,

TTSMetrics

, etc.). 2. Inspect Metrics Content: Try logging the actual metrics objects to see if they have the right structure and properties you expect. 3. Add Debug Logging: Put some debug logs inside the

_on_metrics_collected

handler to confirm that

usage_collector.collect

is being called and to check what metrics are coming through. If you’re still stuck after trying these, just let me know! I’m here to help and we can dig a little deeper together. Sources: examples/voice_agents/basic_agent.py | Capturing metrics | LiveKit Docs | agents/src/metrics/usage_collector.ts

give me an example of how to collect metrics and display summary in the end

Here’s a friendly example showing how you can collect metrics using

UsageCollector

and then display a handy summary at the end: Python Example

from livekit.agents import metrics, MetricsCollectedEvent

# Create a usage collector instance
usage_collector = metrics.UsageCollector()

# Listen for metrics collection events
@session.on("metrics_collected")
def _on_metrics_collected(ev: MetricsCollectedEvent):
    usage_collector.collect(ev.metrics)

async def log_usage():
    summary = usage_collector.get_summary()
    <http://logger.info|logger.info>(f"Usage: {summary}")

# At shutdown, generate and log the summary from the usage collector
ctx.add_shutdown_callback(log_usage)

Complete Python Agent Example

import logging
from livekit.agents import (
    AgentSession,
    JobContext,
    metrics,
)
from livekit.plugins import deepgram, openai

logger = logging.getLogger("basic-agent")

async def entrypoint(ctx: JobContext):
    session = AgentSession(
        vad=ctx.proc.userdata["vad"],
        llm=openai.LLM(model="gpt-4o-mini"),
        stt=deepgram.STT(model="nova-3"),
        tts=openai.TTS(voice="ash"),
    )

    # Create usage collector and set up metrics collection
    usage_collector = metrics.UsageCollector()

    @session.on("metrics_collected")
    def _on_metrics_collected(ev: MetricsCollectedEvent):
        metrics.log_metrics(ev.metrics)  # Log individual metrics
        usage_collector.collect(ev.metrics)  # Collect for summary

    async def log_usage():
        summary = usage_collector.get_summary()
        <http://logger.info|logger.info>(f"Usage: {summary}")

    # Register shutdown callback to log final usage summary
    ctx.add_shutdown_callback(log_usage)

    await session.start(agent=MyAgent(), room=ctx.room)

Usage Summary Structure The

UsageSummary

includes these helpful metrics: • llm_prompt_tokens: How many LLM prompt tokens were used • llm_prompt_cached_tokens: Number of cached prompt tokens • llm_completion_tokens: How many LLM completion tokens were generated • tts_characters_count: Number of characters processed by TTS • tts_audio_duration: Duration of TTS audio generated • stt_audio_duration: Duration of STT audio processed If you’d like me to explain anything further or share more examples, just let me know—I’m here to help! Sources: Capturing metrics | LiveKit Docs | examples/voice_agents/multi_agent.py | agents/src/metrics/usage_collector.ts