feat(metrics): Add V3 background segmentation metrics to media backend via protobuf

  - Add video processor pipeline metrics (frame rate, per-processor latency) via protobuf signaling
  - Add CDN processor performance metrics (segmentation duration, effect render, CPU usage) via observer
  - Add metric dimensions for processor name, model type, and delegate type
  - Add numeric initialization metrics (asset loading time, compatibility, processor creation status)
  - Extend SignalingProtocol.proto with metric type enums 114-128 and dimension types 3-5
  - Simplify BackgroundSegmentationInitializationMetrics to numeric-only interface for protobuf compatibility
  - Remove per-frame reportProcessorError in favor of aggregated CDN errorCount
  - Rewrite BackgroundSegmentationMetrics.test.ts for new interface
  - Add new tests to BackgroundSegmentationVideoFrameProcessor.test.ts
  - Add proper assertions to StatsCollector tests

Author: harshhv-dev

CHANGELOG.md

@@ -12,9 +12,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added CPU pressure state reporting via the [Compute Pressure API](https://developer.mozilla.org/en-US/docs/Web/API/Compute_Pressure_API), sent to the backend as the `CPU_PRESSURE_STATE` client metric where supported.
 - Added `BackgroundSegmentationVideoFrameProcessor` with CDN asset loading, request deduplication, and browser compatibility checking (WebGL2, WASM, Workers)
 - Added configurable blur strength (low/medium/high) and support for `selfie_general` and `selfie_multiclass` model types
-- Added `BackgroundSegmentationMetrics` observer for StatsCollector integration
 - Added dynamic filter switching via `setConfig`/`setModelType` without processor recreation
-- Added video processor metrics collection (frame rate, per-processor latency) via StatsCollector
+- Added video processor pipeline metrics (frame rate, per-processor latency) sent to the media backend via protobuf signaling
+- Added CDN processor performance metrics (segmentation duration, effect render time, CPU usage, error count) via `BackgroundSegmentationMetricsObserver`
+- Added metric dimensions for processor name, model type, and delegate type
+- Added numeric initialization metrics (asset loading time, compatibility status, processor creation status)
 - Added event publishing for filter lifecycle (`backgroundFilterStarted`, `backgroundFilterConfigSelected`, `backgroundFilterFailed`)
 - Added V3-specific fields to `VideoFXEventAttributes`
 

demos/browser/package-lock.json

@@ -322,6 +322,22 @@ message SdkMetric {
         // Reported via the Compute Pressure API (https://developer.mozilla.org/en-US/docs/Web/API/Compute_Pressure_API).
         // Values: 0 = nominal, 1 = fair, 2 = serious, 3 = critical.
         CPU_PRESSURE_STATE = 113;
+
+        VIDEO_BACKGROUND_SEGMENTATION_DURATION_MS = 114;
+        VIDEO_BACKGROUND_SEGMENTATION_EFFECT_RENDER_DURATION_MS = 115;
+        VIDEO_BACKGROUND_SEGMENTATION_FRAMES_PER_SEGMENTATION = 116;
+        VIDEO_BACKGROUND_SEGMENTATION_CPU_USAGE_PERCENT = 117;
+        VIDEO_BACKGROUND_SEGMENTATION_INITIALIZATION_DURATION_MS = 118;
+        VIDEO_BACKGROUND_SEGMENTATION_INITIALIZATION_FAILURE = 119;
+        VIDEO_BACKGROUND_SEGMENTATION_ERROR_COUNT = 120;
+        VIDEO_BACKGROUND_SEGMENTATION_FRAMES_SUBMITTED = 121;
+        VIDEO_BACKGROUND_SEGMENTATION_FRAMES_SEGMENTED = 122;
+        VIDEO_PIPELINE_FRAME_RATE = 123;
+        VIDEO_PROCESSOR_LATENCY_MS = 124;
+        VIDEO_BACKGROUND_SEGMENTATION_ASSET_LOADING_FAILURE = 125;
+        VIDEO_BACKGROUND_SEGMENTATION_ASSET_LOADING_TIME_MS = 126;
+        VIDEO_BACKGROUND_SEGMENTATION_COMPATIBILITY_FAILURE = 127;
+        VIDEO_BACKGROUND_SEGMENTATION_PROCESSOR_CREATION_FAILURE = 128;
     }
     optional Type type = 1;
     optional double value = 2;
@@ -345,6 +361,9 @@ message SdkStreamDimension {
     enum Type {
         VIDEO_ENCODER_NAME = 1;
         VIDEO_DECODER_NAME = 2;
+        VIDEO_BACKGROUND_SEGMENTATION_MODEL_TYPE = 3;
+        VIDEO_BACKGROUND_SEGMENTATION_DELEGATE_TYPE = 4;
+        VIDEO_PROCESSOR_NAME = 5;
     }
     optional Type type = 1;
     optional SdkDimensionValue value = 2;

protocol/SignalingProtocol.proto

@@ -170,9 +170,13 @@ walk('src')
 
     if (typeToImport === 'BackgroundSegmentationMetrics') {
       importStrings.push(`import { BackgroundSegmentationMetricsObserver } from '${pathToImport}/BackgroundSegmentationMetrics';`);
-      importStrings.push(`import { BackgroundSegmentationMetricReport } from '${pathToImport}/BackgroundSegmentationMetrics';`);
+      importStrings.push(`import { BackgroundSegmentationInitializationMetrics } from '${pathToImport}/BackgroundSegmentationMetrics';`);
+      importStrings.push(`import { BackgroundSegmentationInitializationStatus } from '${pathToImport}/BackgroundSegmentationMetrics';`);
+      importStrings.push(`import { BackgroundSegmentationProcessorMetrics } from '${pathToImport}/BackgroundSegmentationMetrics';`);
       exportStrings.push(`BackgroundSegmentationMetricsObserver`);
-      exportStrings.push(`BackgroundSegmentationMetricReport`);
+      exportStrings.push(`BackgroundSegmentationInitializationMetrics`);
+      exportStrings.push(`BackgroundSegmentationInitializationStatus`);
+      exportStrings.push(`BackgroundSegmentationProcessorMetrics`);
     }
   });
 

script/barrelize.js

@@ -3,38 +3,64 @@
 
 import Logger from '../logger/Logger';
 
+export enum BackgroundSegmentationInitializationStatus {
+  SUCCESS = 0,
+  FAILURE = 1,
+}
+
 /**
- * [[BackgroundSegmentationMetricReport]] will contain metrics reported
- * by the [[BackgroundSegmentationVideoFrameProcessor]]
+ * [[BackgroundSegmentationInitializationMetrics]] contains metrics reported
+ * once per processor creation by [[BackgroundSegmentationVideoFrameProcessor]].
  */
-export class BackgroundSegmentationMetricReport {
-  metricName: string = '';
-  timestamp: number = 0;
-  assetType?: string;
-  loadTimeMs?: number;
-  success?: number;
-  error?: string;
-  errorType?: string;
-  errorMessage?: string;
-  modelType?: string;
-  isCompatible?: boolean;
-  missingFeatures?: string;
+export interface BackgroundSegmentationInitializationMetrics {
+  assetLoadingStatus: BackgroundSegmentationInitializationStatus;
+  assetLoadingTimeMs: number;
+  compatibilityStatus: BackgroundSegmentationInitializationStatus;
+  processorCreationStatus: BackgroundSegmentationInitializationStatus;
+}
+
+export interface BackgroundSegmentationProcessorMetrics {
+  segmentationDurationMs: number;
+  effectRenderDurationMs: number;
+  framesPerSegmentation: number;
+  framesSubmitted: number;
+  framesSegmented: number;
+  estimatedCPUUsagePercentage: number;
+  modelType: string;
+  delegateType: string;
+  initializationDurationMs?: number;
+  initializationFailure?: number;
+  errorCount: number;
 }
 
 /**
  * Observer interface for receiving background segmentation metrics
  */
 export interface BackgroundSegmentationMetricsObserver {
-  backgroundSegmentationMetricsDidReceive(metricReport: BackgroundSegmentationMetricReport): void;
+  backgroundSegmentationInitializationMetricsDidReceive(
+    metricReport: BackgroundSegmentationInitializationMetrics
+  ): void;
+  backgroundSegmentationProcessorMetricsDidReceive(
+    report: BackgroundSegmentationProcessorMetrics
+  ): void;
 }
 
 /**
- * Metrics collection for background segmentation processing
+ * Metrics collection for background segmentation processing.
+ * Collects one-time processor creation metrics and periodic CDN performance metrics.
  */
 export default class BackgroundSegmentationMetrics {
   private static readonly MAX_BUFFERED_METRICS = 100;
   private metricsCollector: BackgroundSegmentationMetricsObserver | undefined;
-  private bufferedMetrics: BackgroundSegmentationMetricReport[] = [];
+  private bufferedMetrics: BackgroundSegmentationInitializationMetrics[] = [];
+
+  private _assetLoadingStatus: BackgroundSegmentationInitializationStatus =
+    BackgroundSegmentationInitializationStatus.SUCCESS;
+  private _assetLoadingTimeMs: number = 0;
+  private _compatibilityStatus: BackgroundSegmentationInitializationStatus =
+    BackgroundSegmentationInitializationStatus.SUCCESS;
+  private _processorCreationStatus: BackgroundSegmentationInitializationStatus =
+    BackgroundSegmentationInitializationStatus.SUCCESS;
 
   constructor(
     private logger: Logger,
@@ -65,58 +91,48 @@ export default class BackgroundSegmentationMetrics {
     });
   }
 
-  reportAssetLoadingResult(assetType: string, error?: string, loadTimeMs?: number): void {
-    try {
-      const metricReport = new BackgroundSegmentationMetricReport();
-      metricReport.metricName = 'BackgroundSegmentationAssetLoadingResult';
-      metricReport.assetType = assetType;
-      metricReport.success = error ? 0 : 1;
-      metricReport.error = error;
-      metricReport.loadTimeMs = loadTimeMs;
-      metricReport.timestamp = Date.now();
-
-      this.emitMetricReport(metricReport);
-    } catch (err) {
-      this.logger.warn(
-        `[BackgroundSegmentationMetrics] Failed to report asset loading status: ${err}`
-      );
-    }
+  reportCompatibilityCheck(isCompatible: boolean): void {
+    this._compatibilityStatus = isCompatible
+      ? BackgroundSegmentationInitializationStatus.SUCCESS
+      : BackgroundSegmentationInitializationStatus.FAILURE;
   }
 
-  reportProcessorError(errorType: string, errorMessage: string, modelType: string): void {
-    try {
-      const metricReport = new BackgroundSegmentationMetricReport();
-      metricReport.metricName = 'BackgroundSegmentationProcessorError';
-      metricReport.errorType = errorType;
-      metricReport.errorMessage = errorMessage;
-      metricReport.modelType = modelType;
-      metricReport.timestamp = Date.now();
-
-      this.emitMetricReport(metricReport);
-    } catch (error) {
-      this.logger.warn(
-        `[BackgroundSegmentationMetrics] Failed to report processor error: ${error}`
-      );
-    }
+  reportAssetLoadingResult(error?: string, loadTimeMs?: number): void {
+    this._assetLoadingStatus = error
+      ? BackgroundSegmentationInitializationStatus.FAILURE
+      : BackgroundSegmentationInitializationStatus.SUCCESS;
+    this._assetLoadingTimeMs = loadTimeMs ?? 0;
   }
 
-  reportCompatibilityCheck(isCompatible: boolean, missingFeatures: string[]): void {
-    try {
-      const metricReport = new BackgroundSegmentationMetricReport();
-      metricReport.metricName = 'BackgroundSegmentationCompatibilityCheck';
-      metricReport.isCompatible = isCompatible;
-      metricReport.missingFeatures = missingFeatures.join(',');
-      metricReport.timestamp = Date.now();
+  reportProcessorError(): void {
+    this._processorCreationStatus = BackgroundSegmentationInitializationStatus.FAILURE;
+  }
+
+  emitInitializationMetrics(): void {
+    const report: BackgroundSegmentationInitializationMetrics = {
+      assetLoadingStatus: this._assetLoadingStatus,
+      assetLoadingTimeMs: this._assetLoadingTimeMs,
+      compatibilityStatus: this._compatibilityStatus,
+      processorCreationStatus: this._processorCreationStatus,
+    };
 
-      this.emitMetricReport(metricReport);
+    this.emitMetricReport(report);
+  }
+
+  reportPerformance(report: BackgroundSegmentationProcessorMetrics): void {
+    if (!this.metricsCollector) {
+      return;
+    }
+    try {
+      this.metricsCollector.backgroundSegmentationProcessorMetricsDidReceive(report);
     } catch (error) {
       this.logger.warn(
-        `[BackgroundSegmentationMetrics] Failed to report compatibility check: ${error}`
+        `[BackgroundSegmentationMetrics] Failed to send performance report to collector: ${error}`
       );
     }
   }
 
-  private emitMetricReport(metricReport: BackgroundSegmentationMetricReport): void {
+  private emitMetricReport(metricReport: BackgroundSegmentationInitializationMetrics): void {
     if (!this.metricsCollector) {
       if (this.bufferedMetrics.length >= BackgroundSegmentationMetrics.MAX_BUFFERED_METRICS) {
         this.bufferedMetrics.shift();
@@ -126,7 +142,7 @@ export default class BackgroundSegmentationMetrics {
     }
 
     try {
-      this.metricsCollector.backgroundSegmentationMetricsDidReceive(metricReport);
+      this.metricsCollector.backgroundSegmentationInitializationMetricsDidReceive(metricReport);
     } catch (error) {
       this.logger.warn(
         `[BackgroundSegmentationMetrics] Failed to send metric report to collector: ${error}`