From c259a6a73bcc8ad4b571aa974f4f7f078d5380af Mon Sep 17 00:00:00 2001
From: Mark Backman <mark@daily.co>
Date: Thu, 26 Feb 2026 19:52:34 -0500
Subject: [PATCH] Deprecate processing metrics (ProcessingMetricsData)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add deprecation warnings to start_processing_metrics() and
stop_processing_metrics() on FrameProcessorMetrics and FrameProcessor.
Mark ProcessingMetricsData as deprecated in docstring. All existing
behavior is preserved — the warnings inform users that these will be
removed in a future version.
---
 changelog/3852.deprecated.md                     |  1 +
 src/pipecat/metrics/metrics.py                   |  4 ++++
 src/pipecat/processors/frame_processor.py        | 16 ++++++++++++++++
 .../metrics/frame_processor_metrics.py           |  8 ++++++++
 4 files changed, 29 insertions(+)
 create mode 100644 changelog/3852.deprecated.md

diff --git a/changelog/3852.deprecated.md b/changelog/3852.deprecated.md
new file mode 100644
index 000000000..666c7c58a
--- /dev/null
+++ b/changelog/3852.deprecated.md
@@ -0,0 +1 @@
+- Deprecated `ProcessingMetricsData` and `start_processing_metrics()`/`stop_processing_metrics()` on `FrameProcessor` and `FrameProcessorMetrics`. These metrics don't accurately depict a service's performance. Instead, TTFB metrics are recommended. Processing metrics will be removed in the 1.0.0 version.
diff --git a/src/pipecat/metrics/metrics.py b/src/pipecat/metrics/metrics.py
index 2030306e5..37ab99447 100644
--- a/src/pipecat/metrics/metrics.py
+++ b/src/pipecat/metrics/metrics.py
@@ -41,6 +41,10 @@ class TTFBMetricsData(MetricsData):
 class ProcessingMetricsData(MetricsData):
     """General processing time metrics data.
 
+    .. deprecated:: 0.0.104
+        Processing metrics are deprecated and will be removed in a future version.
+        Use TTFB metrics instead.
+
     Parameters:
         value: Processing time measurement in seconds.
     """
diff --git a/src/pipecat/processors/frame_processor.py b/src/pipecat/processors/frame_processor.py
index baa52cc70..3e90968fe 100644
--- a/src/pipecat/processors/frame_processor.py
+++ b/src/pipecat/processors/frame_processor.py
@@ -441,19 +441,35 @@ class FrameProcessor(BaseObject):
             if frame:
                 await self.push_frame(frame)
 
+    _processing_metrics_warned = False
+
     async def start_processing_metrics(self, *, start_time: Optional[float] = None):
         """Start processing metrics collection.
 
+        .. deprecated:: 0.0.104
+            Processing metrics are deprecated and will be removed in a future version.
+            Use TTFB metrics instead.
+
         Args:
             start_time: Optional timestamp to use as the start time. If None,
                 uses the current time.
         """
         if self.can_generate_metrics() and self.metrics_enabled:
+            if not FrameProcessor._processing_metrics_warned:
+                FrameProcessor._processing_metrics_warned = True
+                logger.warning(
+                    "Processing metrics are deprecated and will be removed in a future version. "
+                    "Use TTFB metrics instead."
+                )
             await self._metrics.start_processing_metrics(start_time=start_time)
 
     async def stop_processing_metrics(self, *, end_time: Optional[float] = None):
         """Stop processing metrics collection and push results.
 
+        .. deprecated:: 0.0.104
+            Processing metrics are deprecated and will be removed in a future version.
+            Use TTFB metrics instead.
+
         Args:
             end_time: Optional timestamp to use as the end time. If None, uses
                 the current time.
diff --git a/src/pipecat/processors/metrics/frame_processor_metrics.py b/src/pipecat/processors/metrics/frame_processor_metrics.py
index 7a52895a2..ef637b5ad 100644
--- a/src/pipecat/processors/metrics/frame_processor_metrics.py
+++ b/src/pipecat/processors/metrics/frame_processor_metrics.py
@@ -150,6 +150,10 @@ class FrameProcessorMetrics(BaseObject):
     async def start_processing_metrics(self, *, start_time: Optional[float] = None):
         """Start measuring processing time.
 
+        .. deprecated:: 0.0.104
+            Processing metrics are deprecated and will be removed in a future version.
+            Use TTFB metrics instead.
+
         Args:
             start_time: Optional timestamp to use as the start time. If None,
                 uses the current time.
@@ -159,6 +163,10 @@ class FrameProcessorMetrics(BaseObject):
     async def stop_processing_metrics(self, *, end_time: Optional[float] = None):
         """Stop processing time measurement and generate metrics frame.
 
+        .. deprecated:: 0.0.104
+            Processing metrics are deprecated and will be removed in a future version.
+            Use TTFB metrics instead.
+
         Args:
             end_time: Optional timestamp to use as the end time. If None, uses
                 the current time.