validationMetadata property

  1. @override
DetectorMetadata get validationMetadata
override

Metadata for this detector. Must be non-null on shipping detectors — the audit test gates this.

This getter belongs to package:sleuth/validation.dart and is outside Sleuth's semver promise, also on main-API detectors that override it.

Implementation

@override
DetectorMetadata get validationMetadata => const DetectorMetadata(
  tier: EvidenceTier.reproducerOnly,
  rationale:
      'Hybrid detector with a frame leg, a VM leg and a structural leg. '
      'On the frame leg (every tier), `processFrame` reads the per-frame '
      '`FrameTiming` UI (build, layout and paint) and raster durations. A '
      'frame is raster-dominant when UI is above 0, raster is above the '
      'frame\'s own budget (the frame missed its deadline on the raster '
      'thread) and above `maxFrameRasterFloorUs` (default 8000us, below '
      'every budget up to 120 Hz), and raster is above 2.0 times UI. '
      '`raster_dominance` warns (`likely`, source `frameTiming`) at 3 '
      'dominant frames inside a 1 s span and is critical at 10, over a '
      '64-entry ring that keeps the last second before the newest frame '
      'across scans and counts only spans that hold a frame that arrived '
      'since the last scan, so a burst is reported once. Recorded frames '
      'from a Galaxy A07 (90 Hz) and an iPhone 12 pin the split: the GPU '
      'Pressure, Cupertino blur and IntrinsicHeight demos on the Galaxy '
      'dropped 26 to 54 such frames a second, other screens 5 or fewer. '
      'Two Galaxy recordings made while Sleuth requested the timeline '
      'every 500 ms read warning from 3 frames 500 ms apart, which the '
      'request held on the raster thread. The same screens recorded with '
      'the timeline stream read none. '
      'Frames inside the startup window (`startupPhaseWindowSeconds` after '
      'Dart entry) do not count on either leg. On the VM leg, each scan '
      'reads the batch with the slowest raster frame since the last scan '
      'and clears it, so idle polls never judge old values; a route change '
      'clears it too. Each raster frame in a batch is set against the UI '
      'time of an average frame in that batch (UI total over raster '
      'frames), because the timeline does not pair them. When the frame '
      'leg fires and at least one VM frame since the last scan is over '
      'the budget with the ratio above 2.0, the issue is `confirmed`; '
      'otherwise it is `likely`, because Impeller raster durations can '
      'include present back-pressure. When no frames arrived since the '
      'last scan (`FrameTimingDetector` disabled), the VM leg emits on its '
      'own once one poll holds 3 such frames, critical at 10. '
      '`expensive_gpu_nodes` (structural) '
      'gates on a subtree size strictly above 5 over 4 RenderObject '
      'checks. These are `RenderOpacity` (an opacity-value short-circuit '
      'at 0.0 and 1.0, pinned by a 4-axis matrix), `RenderClipPath` '
      '(except the clip a transparency `Material` builds for its own '
      'shape), `RenderBackdropFilter` (3 sigma bands: at most 2.0 is '
      'suppressed, above 2.0 up to 10.0 is a warning highlight, above '
      '10.0 is a critical highlight; a disabled filter is skipped; the '
      'sigma is read from the filter fields, because profile builds drop '
      'the `toString` it was once parsed from; a blur composed with a '
      'matrix has no known sigma and counts; a blur drawn by a Cupertino '
      'bar or dialog names that widget) and `RenderShaderMask`. One more '
      'check runs at widget level (`element.widget is ColorFiltered`), '
      'because ColorFiltered has no public RenderObject type. The '
      '`expensive_gpu_nodes` issue severity is always `warning`. An '
      'Opacity-wrapping-Opacity test verifies the nested-expense '
      'subtree-stack arithmetic. For confidence, `expensive_gpu_nodes` is '
      '`likely` when either raster leg qualified and `possible` '
      'otherwise. The VM-disconnect setter removes a VM-sourced '
      '`raster_dominance`, returns a VM-confirmed frame-leg issue to '
      '`likely`, and downgrades `expensive_gpu_nodes` only when no '
      'frame-sourced `raster_dominance` remains. '
      'Runtime verification covers the frame leg of `raster_dominance` '
      '(warning at 3, critical at 10) on an iPhone 12 at 60 Hz with '
      'Impeller on Metal. A capture screen draws a prerecorded picture of '
      '700 stroked paths on a chosen run of consecutive frames. Each such '
      'frame cost the raster thread 28 to 80 ms against under 6 ms of UI. '
      'The screen counts the dominant frames in its busiest one-second '
      'span from its own `FrameTiming` listener with the same rule. The '
      'issue stamps that span count as `observedDominantFrames`, and the '
      'screen stashes a leg only when the most the detector stamped '
      'equals the screen\'s count. Every heavy frame must be dominant. The '
      'frame that hides the picture, and the first frame drawn after it '
      'when it starts within 250 ms, belong to the run, because their '
      'raster time can include waiting for the GPU to finish the heavy '
      'frames. A dominant frame anywhere else refuses the leg as ambient; '
      'the screen does not subtract it. The warning legs read 1 dominant '
      'frame (silent), 3 and 6; the critical legs read 6 (a warning '
      'only), 11 and 20 within 718 ms. The detector matched the screen in '
      'every leg, and the critical above leg wrote 8 and then 20 across '
      'two scans. '
      'The leg narrows the timeline to the Dart stream, so the VM leg '
      'sees no raster frames and the records are `likely`; the step to '
      '`confirmed` that the VM leg gives in other sessions is not part of '
      'the captures. `expensive_gpu_nodes` has no runtime verification.',
  reproducerPath: 'test/validation/gpu_pressure_reproducer_test.dart',
  coveredStableIds: {'raster_dominance', 'expensive_gpu_nodes'},
  perStableIdTier: {'raster_dominance': EvidenceTier.runtimeVerified},
  profileCapturePaths: [
    'test/validation/captures/gpu_pressure/raster_dominance_below.json',
    'test/validation/captures/gpu_pressure/raster_dominance_at.json',
    'test/validation/captures/gpu_pressure/raster_dominance_above.json',
  ],
  // The warning fires at 3 dominant frames in a one-second span. The at
  // band is [3, 4.5] frames and the above band (4.5, 9]. The above band
  // ends below 10, where the detector records critical instead.
  bracketThreshold: 3,
  bracketUnit: 'frames',
  bracketStableId: 'raster_dominance',
  bracketSeverityLabel: 'warning',
  bracketAtTolerance: 0.5,
  aboveCeilingMultiplier: 3.0,
  observedAxisArgKey: 'observedDominantFrames',
  // The tolerance is relative, so any count below 100 must match exactly.
  observedAxisTolerance: 0.01,
  observedAxisReduction: 'max',
  bracketRequireUniqueDetectedAtMicros: true,
  coveredThresholds: {
    'raster_dominance.warning',
    'raster_dominance.critical',
  },
  additionalBrackets: [
    // The critical fires at 10. The at band is [10, 15] frames and the
    // above band (15, 25]. A run writes one or two critical records, so
    // there is no in-band minimum.
    BracketSpec(
      stableId: 'raster_dominance',
      severityLabel: 'critical',
      threshold: 10,
      unit: 'frames',
      coveredThresholds: {'raster_dominance.critical'},
      profileCapturePaths: [
        'test/validation/captures/gpu_pressure/raster_dominance_critical_below.json',
        'test/validation/captures/gpu_pressure/raster_dominance_critical_at.json',
        'test/validation/captures/gpu_pressure/raster_dominance_critical_above.json',
      ],
      atTolerance: 0.5,
      aboveCeilingMultiplier: 2.5,
      observedAxisArgKey: 'observedDominantFrames',
      observedAxisTolerance: 0.01,
      observedAxisReduction: 'max',
      requireUniqueDetectedAtMicros: true,
      requireDetectorTraceRecord: true,
    ),
  ],
);