validationMetadata property
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,
),
],
);