metrics

Metrics data models for Pipecat framework.

This module defines Pydantic models for various types of metrics data collected throughout the pipeline, including timing, token usage, and processing statistics.

class pipecat.metrics.metrics.MetricsData(*, processor: str, model: str | None = None)[source]

Bases: BaseModel

Base class for all metrics data.

Parameters:

processor – Name of the processor generating the metrics.
model – Optional model name associated with the metrics.

processor: str

model: str | None

class pipecat.metrics.metrics.TTFBMetricsData(*, processor: str, model: str | None = None, value: float)[source]

Bases: MetricsData

Time To First Byte (TTFB) metrics data.

Parameters:: value – TTFB measurement in seconds.

value: float

class pipecat.metrics.metrics.TTFAMetricsData(*, processor: str, model: str | None = None, ttfa: float, ttfb: float, leading_silence: float)[source]

Bases: MetricsData

Time To First Audio (TTFA) metrics data.

Measures the time from a TTS request to the first audible audio sample, i.e. time-to-first-byte plus any leading silence the service pads onto the start of its response. ttfa is reported with its breakdown so consumers can see how much of the perceived latency is silence padding rather than service response time, without correlating a separate TTFBMetricsData.

Parameters:

ttfa – TTFA measurement in seconds (ttfb plus leading_silence).
ttfb – Time-to-first-byte that TTFA builds on, in seconds. This mirrors the standalone TTFBMetricsData (emitted earlier) for convenience; it is not a separate measurement, so don’t aggregate both.
leading_silence – Silence padding before the first audible sample, in seconds (ttfa minus ttfb).

ttfa: float

ttfb: float

leading_silence: float

class pipecat.metrics.metrics.ProcessingMetricsData(*, processor: str, model: str | None = None, value: float)[source]

Bases: MetricsData

General processing time metrics data.

Parameters:: value – Processing time measurement in seconds.

value: float

class pipecat.metrics.metrics.LLMTokenUsage(*, prompt_tokens: int, completion_tokens: int, total_tokens: int, cache_read_input_tokens: int | None = None, cache_creation_input_tokens: int | None = None, reasoning_tokens: int | None = None, input_audio_tokens: int | None = None, output_audio_tokens: int | None = None, cache_read_input_audio_tokens: int | None = None)[source]

Bases: BaseModel

Token usage statistics for LLM operations.

Parameters:

prompt_tokens – Number of tokens in the input prompt.
completion_tokens – Number of tokens in the generated completion.
total_tokens – Total number of tokens used (prompt + completion).
cache_read_input_tokens – Number of tokens read from cache, if applicable.
cache_creation_input_tokens – Number of tokens used to create cache entries, if applicable.
reasoning_tokens – Number of completion tokens used for reasoning, if applicable.
input_audio_tokens – Number of prompt tokens that were audio, if applicable.
output_audio_tokens – Number of completion tokens that were audio, if applicable.
cache_read_input_audio_tokens – Number of cache-read tokens that were audio, if applicable.

prompt_tokens: int

completion_tokens: int

total_tokens: int

cache_read_input_tokens: int | None

cache_creation_input_tokens: int | None

reasoning_tokens: int | None

input_audio_tokens: int | None

output_audio_tokens: int | None

cache_read_input_audio_tokens: int | None

class pipecat.metrics.metrics.LLMUsageMetricsData(*, processor: str, model: str | None = None, value: LLMTokenUsage)[source]

Bases: MetricsData

LLM token usage metrics data.

Parameters:: value – Token usage statistics for the LLM operation.

value: LLMTokenUsage

class pipecat.metrics.metrics.STTUsage(*, audio_seconds: float)[source]

Bases: BaseModel

Usage statistics for STT operations.

Reports raw usage, not cost. Values are incremental deltas since the previous usage report; consumers sum them across a session.

Continuous STT services stream all input audio (including silence), so their summed audio_seconds approximates the stream duration — which is what most streaming providers bill. Segmented STT services submit only the detected speech segments, so their sum covers just those segments.

Parameters:: audio_seconds – Client-measured seconds of audio submitted to the service since the last usage report.

audio_seconds: float

class pipecat.metrics.metrics.STTUsageMetricsData(*, processor: str, model: str | None = None, value: STTUsage)[source]

Bases: MetricsData

Speech-to-Text usage metrics data.

Parameters:: value – Usage statistics for the STT operation.

value: STTUsage

class pipecat.metrics.metrics.TTSUsageMetricsData(*, processor: str, model: str | None = None, value: int)[source]

Bases: MetricsData

Text-to-Speech usage metrics data.

Parameters:: value – Number of characters processed by TTS.

value: int

class pipecat.metrics.metrics.TextAggregationMetricsData(*, processor: str, model: str | None = None, value: float)[source]

Bases: MetricsData

Text aggregation time metrics data.

Measures the time from the first LLM token to the first complete sentence, representing the latency cost of sentence aggregation in the TTS pipeline.

Parameters:: value – Aggregation time in seconds.

value: float

class pipecat.metrics.metrics.TurnMetricsData(*, processor: str, model: str | None = None, is_complete: bool, probability: float, e2e_processing_time_ms: float)[source]

Bases: MetricsData

Metrics data for turn detection predictions.

Parameters:

is_complete – Whether the turn is predicted to be complete.
probability – Confidence probability of the turn completion prediction.
e2e_processing_time_ms – End-to-end processing time in milliseconds, measured from VAD speech-to-silence transition to turn completion.

is_complete: bool

probability: float

e2e_processing_time_ms: float

class pipecat.metrics.metrics.SmartTurnMetricsData(*, processor: str, model: str | None = None, is_complete: bool, probability: float, e2e_processing_time_ms: float, inference_time_ms: float = 0.0, server_total_time_ms: float = 0.0)[source]

Bases: TurnMetricsData

Metrics data for smart turn predictions.

Deprecated since version 0.0.104: Use TurnMetricsData instead. Will be removed in 2.0.0.

Parameters:

inference_time_ms – Time taken for inference in milliseconds.
server_total_time_ms – Total server processing time in milliseconds.

inference_time_ms: float

server_total_time_ms: float