Watchdog Timers

​

Overview

Watchdog timers are used to detect if a Pipecat task is taking longer than expected. By default, if watchdog timers are enabled and a task takes longer than 5 seconds to reset the timer, a warning will be logged. Watchdog timers are very common in real-time applications to detect if things are frozen or taking too much time. Usually, you start the watchdog and you need to keep resetting it before the watchdog timer timeout expires.

In Pipecat, watchdog timers are available if you create a task using the FrameProcessor.create_task() method. If you use asyncio.create_task() or loop.create_task(), watchdog timers will not work.

​

Configuration

Watchdog timers are disabled by default. You can enable and configure them using the following PipelineTask constructor arguments:

It is possible to configure watchdog timers individually for each FrameProcessor, using the same argument names in the constructor, or even per task when creating them with FrameProcessor.create_task().

​

How It Works

Watchdog timers are always available for every created Pipecat task:

1. We enable watchdog timers using enable_watchdog_timers.
2. A task is created with FrameProcessor.create_task() and its watchdog timer is started.
3. The task needs to periodically call self.reset_watchdog() to prevent the watchdog timer to expire
4. If the watchdog timer is not reset a warning will be logged

​

Usage Examples

class MyFrameProcessor(FrameProcessor):

    async def process_frame(self, frame: Frame, direction: FrameDirection):
        await super().process_frame(frame, direction)
        ...
        self._task = self.create_task(self._task_handler())
        ...

    async def _task_handler(self):
        while True:
            item = await self._queue.get()

            ...
            # Perform any processing
            ...
            self.reset_watchdog()

​

Notes

• Watchdog timers are disabled by default
• Watchdog timers only work with Pipecat tasks (use FrameProcessor.create_task())
• Watchdog timers can be enabled and configure globally with PipelineTask, per FrameProcessor or per task