Merge pull request #2411 from heygen-com/07-13-feat_engine_producer_cli_capture_failing_db_frame_index_on_drawelement_verify_fallback

feat(engine,producer,cli): capture failing dB/frame index on drawElement verify fallback

packages/cli/src/commands/render.ts

@@ -2064,6 +2064,9 @@ function trackRenderMetrics(
     deVerifyInitMs: perf?.drawElement?.verifyInitMs,
     deSelfVerifyFallback: perf?.drawElement?.selfVerifyFallback,
     deFallbackReason: perf?.drawElement?.fallbackReason,
+    deFallbackFailedDb: perf?.drawElement?.fallbackFailedDb,
+    deFallbackFrameIndex: perf?.drawElement?.fallbackFrameIndex,
+    deFallbackThresholdDb: perf?.drawElement?.fallbackThresholdDb,
     deBlankSuspects: perf?.drawElement?.blankSuspects,
     deBlankDeterministicAccepts: perf?.drawElement?.blankDeterministicAccepts,
     deBlankRecaptures: perf?.drawElement?.blankRecaptures,

packages/cli/src/telemetry/events.test.ts

@@ -252,6 +252,32 @@ describe("render telemetry events", () => {
     );
   });
 
+  it("carries the failing dB, frame index, and threshold on render_error for a psnr fallback that failed hard afterward", () => {
+    trackRenderError({
+      fps: 30,
+      quality: "standard",
+      docker: false,
+      errorMessage: "worker crashed after a psnr fallback",
+      captureDeParallelRouter: "reverted",
+      captureDeSelfVerifyFallback: true,
+      captureDeFallbackReason: "psnr",
+      captureDeFallbackFailedDb: 28.4,
+      captureDeFallbackFrameIndex: 649,
+      captureDeFallbackThresholdDb: 32,
+    });
+
+    expect(trackEvent).toHaveBeenCalledWith(
+      "render_error",
+      expect.objectContaining({
+        de_fallback_reason: "psnr",
+        de_fallback_failed_db: 28.4,
+        de_fallback_frame_index: 649,
+        de_fallback_threshold_db: 32,
+      }),
+      undefined,
+    );
+  });
+
   it("prefers the explicit perfSummary-sourced de_worker_inversion over the capture-observability fallback on render_complete", () => {
     trackRenderComplete({
       durationMs: 1000,
@@ -272,6 +298,32 @@ describe("render telemetry events", () => {
     );
   });
 
+  it("carries the perfSummary-sourced failing dB, frame index, and threshold on render_complete", () => {
+    trackRenderComplete({
+      durationMs: 1000,
+      fps: 30,
+      quality: "standard",
+      docker: false,
+      gpu: false,
+      deParallelRouter: "reverted",
+      deFallbackReason: "psnr",
+      deFallbackFailedDb: 28.4,
+      deFallbackFrameIndex: 649,
+      deFallbackThresholdDb: 32,
+    });
+
+    expect(trackEvent).toHaveBeenCalledWith(
+      "render_complete",
+      expect.objectContaining({
+        de_fallback_reason: "psnr",
+        de_fallback_failed_db: 28.4,
+        de_fallback_frame_index: 649,
+        de_fallback_threshold_db: 32,
+      }),
+      undefined,
+    );
+  });
+
   it("emits render_preflight_rejected with the low-cardinality issue kind", () => {
     trackRenderPreflightRejected({ kind: "aspect-mismatch" });
     expect(trackEvent).toHaveBeenCalledWith("render_preflight_rejected", {

packages/cli/src/telemetry/events.ts

@@ -54,6 +54,9 @@ export interface RenderObservabilityTelemetryPayload {
   captureDePreRouterWorkers?: number;
   captureDeSelfVerifyFallback?: boolean;
   captureDeFallbackReason?: string;
+  captureDeFallbackFailedDb?: number;
+  captureDeFallbackFrameIndex?: number;
+  captureDeFallbackThresholdDb?: number;
   /** Non-DE parallel-streaming router outcome ("screenshot" | "beginframe" —
    * routed; "eligible_off" — would route but the kill switch is off). */
   captureParallelStream?: string;
@@ -108,6 +111,9 @@ function renderObservabilityEventProperties(props: RenderObservabilityTelemetryP
     de_pre_router_workers: props.captureDePreRouterWorkers,
     de_self_verify_fallback: props.captureDeSelfVerifyFallback,
     de_fallback_reason: props.captureDeFallbackReason,
+    de_fallback_failed_db: props.captureDeFallbackFailedDb,
+    de_fallback_frame_index: props.captureDeFallbackFrameIndex,
+    de_fallback_threshold_db: props.captureDeFallbackThresholdDb,
     capture_parallel_stream: props.captureParallelStream,
     observability_extract_video_count: props.observabilityExtractVideoCount,
     observability_extracted_video_count: props.observabilityExtractedVideoCount,
@@ -173,6 +179,9 @@ export function trackRenderComplete(
     deVerifyInitMs?: number;
     deSelfVerifyFallback?: boolean;
     deFallbackReason?: string;
+    deFallbackFailedDb?: number;
+    deFallbackFrameIndex?: number;
+    deFallbackThresholdDb?: number;
     deBlankSuspects?: number;
     deBlankDeterministicAccepts?: number;
     deBlankRecaptures?: number;
@@ -260,6 +269,9 @@ export function trackRenderComplete(
       de_verify_init_ms: props.deVerifyInitMs,
       de_self_verify_fallback: props.deSelfVerifyFallback,
       de_fallback_reason: props.deFallbackReason,
+      de_fallback_failed_db: props.deFallbackFailedDb,
+      de_fallback_frame_index: props.deFallbackFrameIndex,
+      de_fallback_threshold_db: props.deFallbackThresholdDb,
       de_blank_suspects: props.deBlankSuspects,
       de_blank_deterministic_accepts: props.deBlankDeterministicAccepts,
       de_blank_recaptures: props.deBlankRecaptures,

packages/cli/src/telemetry/renderObservability.test.ts

@@ -81,6 +81,30 @@ describe("renderObservabilityTelemetryPayload — DE inversion/router cohort (fa
     const payload = renderObservabilityTelemetryPayload(makeSummary({}));
     expect(payload.captureDeFallbackReason).toBeUndefined();
   });
+
+  it("carries the failing dB, frame index, and threshold for a psnr fallback, still visible on a hard failure", () => {
+    const payload = renderObservabilityTelemetryPayload(
+      makeSummary({
+        deParallelRouter: "routed",
+        deFallbackReason: "psnr",
+        deFallbackFailedDb: 28.4,
+        deFallbackFrameIndex: 649,
+        deFallbackThresholdDb: 32,
+      }),
+    );
+    expect(payload.captureDeFallbackFailedDb).toBe(28.4);
+    expect(payload.captureDeFallbackFrameIndex).toBe(649);
+    expect(payload.captureDeFallbackThresholdDb).toBe(32);
+  });
+
+  it("leaves failedDb/thresholdDb undefined for a blank/oom/capture_error fallback (no PSNR score exists)", () => {
+    const payload = renderObservabilityTelemetryPayload(
+      makeSummary({ deFallbackReason: "oom", deFallbackFrameIndex: undefined }),
+    );
+    expect(payload.captureDeFallbackFailedDb).toBeUndefined();
+    expect(payload.captureDeFallbackFrameIndex).toBeUndefined();
+    expect(payload.captureDeFallbackThresholdDb).toBeUndefined();
+  });
 });
 
 describe("renderObservabilityTelemetryPayload — non-DE parallel-stream router", () => {

packages/cli/src/telemetry/renderObservability.ts

@@ -46,6 +46,9 @@ export function renderObservabilityTelemetryPayload(
     captureDePreRouterWorkers: capture.dePreRouterWorkers,
     captureDeSelfVerifyFallback: capture.deSelfVerifyFallback,
     captureDeFallbackReason: capture.deFallbackReason,
+    captureDeFallbackFailedDb: capture.deFallbackFailedDb,
+    captureDeFallbackFrameIndex: capture.deFallbackFrameIndex,
+    captureDeFallbackThresholdDb: capture.deFallbackThresholdDb,
     captureParallelStream: capture.captureParallelStream,
     observabilityExtractVideoCount: extraction?.videoCount,
     observabilityExtractedVideoCount: extraction?.extractedVideoCount,