`metrics_collected` is deprecated — what's the right replacement?

Agents
1

We’ve been using metrics_collected to log per-turn metrics in our voice agent:

@session.on("metrics_collected")
def _on_metrics_collected(ev: MetricsCollectedEvent):
    metrics.log_metrics(ev.metrics, logger=logger)

The deprecation warning says to use session_usage_updated instead, but that event gives cumulative session totals via AgentSessionUsage, not per-turn metrics. So it’s not a direct replacement for log_metrics.

Looking at the source, it seems ChatMessage.metrics is the new way to get per-turn latency data, but there’s no documentation on how to use it in practice.

Questions:

  1. Is log_metrics still the right way to log per-turn metrics, or is there a new equivalent?
  2. What’s the intended pattern for accessing per-turn metrics now — listening on conversation_item_added and reading ev.item.metrics?
  3. Any plans to document session_usage_updated and ChatMessage.metrics properly?
2

The best source I can point you to is the release notes for Agents 1.5.0, Release livekit-agents@1.5.0 · livekit/agents · GitHub, there is a ‘Deprecations’ section and table specifying the replacement:

Deprecated Replacement Notes
metrics_collected event session_usage_updated event + ChatMessage.metrics Usage/cost data moves to session_usage_updated; per-turn latency moves to ChatMessage.metrics. Old listeners still work with a deprecation warning.

Looking at the source, it seems ChatMessage.metrics is the new way to get per-turn latency data, but there’s no documentation on how to use it in practice.

It looks like the documentation still talks about metrics_collected, Events and error handling | LiveKit Documentation, so let me check with the docs team, possibly that wasn’t updated yet.

1 Like
3

Confirmed, the docs will be updated in the coming days, apologies for the delay

4

My question is do I need to replicate the log_metrics function or LiveKit will release a native approach for that?

5

My question is do I need to replicate the log_metrics function or LiveKit will release a native approach for that?

Good question… I don’t see an equivalent, and looking at the pre-release docs, it looks like you’ll need to replicate the behaviour.