Pipeline Heartbeats

​

Overview

Pipeline heartbeats provide a way to monitor the health of your pipeline by sending periodic heartbeat frames through the system. When enabled, the pipeline will send heartbeat frames every second and monitor their progress through the pipeline.

​

Enabling Heartbeats

Heartbeats can be enabled by setting enable_heartbeats to True in the PipelineParams:

from pipecat.pipeline.task import PipelineParams, PipelineTask

pipeline = Pipeline([...])
params = PipelineParams(enable_heartbeats=True)
task = PipelineTask(pipeline, params)

​

How It Works

When heartbeats are enabled:

1. The pipeline sends a HeartbeatFrame every second
2. The frame traverses through all processors in the pipeline, from source to sink
3. The pipeline monitors how long it takes for heartbeat frames to complete their journey
4. If a heartbeat frame isn’t received within 5 seconds, a warning is logged

​

Monitoring Output

The system will log:

• Trace-level logs showing heartbeat processing time
• Warning messages if heartbeats aren’t received within the monitoring window

Example warning message:

WARNING    PipelineTask#1: heartbeat frame not received for more than 5.0 seconds

​

Use Cases

Heartbeat monitoring is useful for:

• Detecting pipeline stalls or blockages
• Monitoring processing latency through the pipeline
• Identifying performance issues in specific processors
• Ensuring the pipeline remains responsive

​

Configuration

The heartbeat system uses two key timing constants:

• HEARTBEAT_SECONDS = 1.0 - Interval between heartbeat frames
• HEARTBEAT_MONITOR_SECONDS = 5.0 - Time before warning if no heartbeat received