The @cloudflare/voice package version 0.4.0 adds a new Voice Turn Metrics feature that emits a typed summary for every turn, exposing stage‑level latency and a definitive outcome code.
What Changed: Voice Turn Metrics
Each turn now triggers a turnmetrics event on the VoiceClient. The payload is a VoiceTurnMetrics object that contains:
- A
turnIdthat can be used to correlate logs from the same interaction. - An
outcomefield with one of the following values:completed,no_output,output_limit,content_filtered,model_error,tts_error, oraborted. - Timing measurements for the key stages – speech‑to‑final‑transcript, model‑to‑first‑text, TTS‑to‑first‑audio, and total turn duration. Stages that were not reached are omitted.
Timings are reported as raw elapsed milliseconds and may overlap; they are therefore not additive. The same structure is exposed through the React hooks useVoiceAgent() and useVoiceInput(), although the latter only includes the speech and transcription timings it can observe.
client.addEventListener("turnmetrics", turn => {
console.log(turn.outcome, turn.turnTotalMs);
});
Why It Matters to Engineers
Previously the package only supplied four aggregate metrics that covered successful, non‑empty speech turns. Those aggregates hid failures, aborted sessions, and empty responses. With the new metrics, AI engineers can differentiate between a model that returned no output, hit an output limit, was blocked by content filtering, or encountered an error in the model or TTS pipeline. Cloud and platform engineers gain a concrete latency breakdown that can be correlated with infrastructure metrics, making it possible to pinpoint whether delays stem from transcription, model inference, or audio synthesis.
For DevOps and SRE teams, the per‑turn outcome and stage timings become first‑class observables that can be fed into existing monitoring pipelines. Alerting on unexpected spikes in model_error or prolonged tts_to_first_audio intervals can surface regressions before they affect end users. Security engineers can also see when a turn is terminated by content_filtered, which may indicate policy enforcement at the agent level.
Architectural and Operational Implications
The addition of turnmetrics does not require changes to the underlying WebSocket transport; it is an in‑process event emitted by the client library. However, practitioners should consider the following:
- Instrumentation: Existing logging frameworks need to capture the
turnIdand outcome for correlation with backend logs. - Data volume: Every turn now produces a small JSON object. High‑throughput agents should evaluate storage and retention policies.
- Overlap handling: Because stage timings can overlap, dashboards should display each stage independently rather than summing them.
- Partial data: Turns that abort early will omit later stage timings. Consumers must treat missing fields as “not reached” rather than zero.
- Local debugging: Developers can forward server lifecycle events to the browser console, providing a unified view of client‑side turn metrics and server‑side events during development.
Related CloudNinjas coverage: hands-on guides.
What This Means For Practitioners
Start listening for the turnmetrics event and pipe the payload into your observability stack. Correlate turnId with request IDs on the backend to trace end‑to‑end latency. Build alerts for non‑completed outcomes and for stage latency thresholds that exceed your SLA. During development, enable the server‑to‑browser event forwarding to quickly verify that each stage behaves as expected. By treating the new metrics as a diagnostic surface, teams can reduce guesswork, accelerate root‑cause analysis, and make data‑driven decisions about model selection, TTS providers, and infrastructure sizing.
