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:
'VM-only detector. A hermetic reproducer pins 4 families at the '
'detector entry points (`processHeapSample` and `recordGcCycle`). '
'`gc_pressure` fires above 40 young-generation collections in a '
'10s sliding window, a rate above 240/min, by default; old-gen '
'sweeps and marking starts do not count. Recorded GC dumps from an '
'iPhone 12 and a Galaxy A07 pin the rule: GC Churn fires on both, '
'and Live Waveform is silent at 60 Hz. The threshold is '
'configurable, and '
'the issue stamps the young-generation, old-generation and '
'marking-start split, plus GC pause time when every event in the '
'window has a measured pause. `heap_growing` '
'fires on a slope above 512KB/s sustained for at least 10s. '
'`heap_near_capacity` needs the opt-in `memoryBudgetBytes`. It '
'fires when RSS is at least 80% of the budget in 4 of the last 5 '
'samples and `heap_growing` emitted in the same evaluation. It '
'stays silent when the budget is unset, and RSS-null samples never '
'count. `native_memory_growing` fires when the slope of the '
'RSS-heap gap and the slope of RSS itself are both above 1MB/s '
'over the 30 s window and over each half of it, sustained for at '
'least 10s; RSS stays flat while the Dart heap collects, so the '
'heap sawtooth never fires it, and a one-time jump leaves one half '
'flat. Recorded Galaxy A07 and iPhone 12 staircases (10 MB every '
'2.5 s) fire it, and a Galaxy screen-open jump does not. The '
'reproducer asserts that null rssBytes (web) and the zero-heap and '
'zero-capacity null-coalesce edges emit nothing.\n\n'
'v0.19.3 raises `heap_growing` (warning tier, 512 KB/s) to '
'runtimeVerified via `perStableIdTier`, with one bracket per leg: '
'the canonical bracket reads the sample leg '
'(`observedSlopeBytesPerSec`, 10 s sustained regression) and '
'`additionalBrackets[0]` the floor leg '
'(`observedFloorSlopeBytesPerSec`, idle full collections). Each leg '
'has three on-device captures (iPhone 12, iOS 17.5, Flutter 3.47.6) '
'recorded with the other leg switched off, because every in-span '
'record must carry its bracket\'s key. '
'`MemoryPressureCaptureScreen` calibrates an allocation-loop rate '
'and narrows VM timeline streams to `Dart` only, so heavy '
'allocation does not overflow the ring buffer. It switches '
'StreamResourceDetector off, holds Sleuth\'s own allocation-profile '
'reads and waits for one in flight, settles for 2.5 s, then drives '
'a 45 s sustained-allocation phase inside '
'`Sleuth.markScenarioBegin/End`, with a 600 ms dwell before the end '
'for the detector emission and an 800 ms dwell after it for the '
'VM-service buffer flush. Last, it exports the wrapped JSON through '
'the iOS clipboard. `markScenarioBegin` resets the detector window '
'so the regression slope covers scenario allocation only. Flat '
'samples from before the scenario would otherwise dilute the slope '
'below the threshold. Producer-side dedup keys on each leg\'s '
'first publication time in the growth episode, a stable per-leg '
'identity, so `requireUniqueDetectedAtMicros: true` locks '
'single-issue replay protection. v0.38.0 raises `gc_pressure` '
'(warning) too, through `additionalBrackets[1]`: threshold 41 young '
'collections in the 10 s window (the first count above 240/min), '
'read from `scavengeCount` as the largest in-span value, on three '
'iPhone 12 captures (iOS 17.5, Flutter 3.47.6). The capture screen '
'counts its own isolate\'s young collections over its own VM '
'service connection, holds the young rate at the leg\'s target '
'with a closed allocation loop, and exports its own largest 10 s '
'count; the audit compares that with the detector\'s records '
'within 25 %. Each evaluation over the threshold carries its own '
'identity, so the records follow the count as the window fills '
'from the reset at `markScenarioBegin`. `heap_near_capacity` and '
'`native_memory_growing` stay reproducerOnly. v0.19.18 backfills the `observedSlopeBytesPerSec` '
'extraTraceArgs stamp and the `observedAxisArgKey` declaration on '
'the canonical bracket. The capture screen writes the detector\'s '
'slope into `expectedMagnitude.observed`, so the cross-check reads '
'the same value; the measured operator rate is in the capture '
'notes.\n\n'
'The reproducer skips three upstream hops. (1) '
'`VmServiceClient.getMemoryUsage` repacks `vm_service.MemoryUsage` '
'into `HeapSample` and falls back from null to 0 on the heap, '
'capacity and external fields. The reproducer exercises the '
'zero-coalesce edge but not the repack. (2) `EventStreams.kGC`, '
'then `_onGcEvent`, then `recordGcCycle` is the authoritative '
'per-cycle GC signal. The reproducer calls `recordGcCycle` directly '
'and skips the VM-service stream plumbing. (3) '
'`VmServiceClient._readRssBytes()` calls `ProcessInfo.currentRss`, '
'the OS-level RSS collection boundary. It sources '
'`HeapSample.rssBytes`, so it gates `native_memory_growing` (which '
'reads RSS and `nativeBytes = rssBytes - heapUsage`) and '
'`heap_near_capacity`. The reproducer exercises the null-rssBytes '
'edge (web, unusual embeddings) but not the `ProcessInfo` call and '
'its try/catch. This detector does not use the `gcEvents` list from '
'TimelineParser, because that list over-counts GC sub-phase events '
'5 to 15 times per cycle. The controller boundary verifies that '
'design choice, not this reproducer.',
reproducerPath: 'test/validation/memory_pressure_reproducer_test.dart',
profileCapturePaths: [
'test/validation/captures/memory_pressure/heap_growing_below.json',
'test/validation/captures/memory_pressure/heap_growing_at.json',
'test/validation/captures/memory_pressure/heap_growing_above.json',
],
bracketThreshold: 512000,
bracketUnit: 'bytes/sec',
bracketStableId: 'heap_growing',
bracketSeverityLabel: 'warning',
bracketAtTolerance: 0.50,
aboveCeilingMultiplier: 2.0,
observedAxisArgKey: 'observedSlopeBytesPerSec',
coveredStableIds: {
'gc_pressure',
'heap_growing',
'heap_near_capacity',
'native_memory_growing',
},
perStableIdTier: {
'heap_growing': EvidenceTier.runtimeVerified,
'gc_pressure': EvidenceTier.runtimeVerified,
},
coveredThresholds: {'heap_growing.warning', 'gc_pressure.warning'},
bracketRequireUniqueDetectedAtMicros: true,
// The floor leg's bracket. Its records carry
// `observedFloorSlopeBytesPerSec` and never the sample leg's key, so
// each bracket reads only its own leg; each triad was recorded with
// the other leg switched off.
additionalBrackets: [
BracketSpec(
stableId: 'heap_growing',
severityLabel: 'warning',
threshold: 512000,
unit: 'bytes/sec',
coveredThresholds: {'heap_growing.warning'},
profileCapturePaths: [
'test/validation/captures/memory_pressure_floor/heap_growing_floor_below.json',
'test/validation/captures/memory_pressure_floor/heap_growing_floor_at.json',
'test/validation/captures/memory_pressure_floor/heap_growing_floor_above.json',
],
atTolerance: 0.50,
aboveCeilingMultiplier: 2.0,
observedAxisArgKey: 'observedFloorSlopeBytesPerSec',
observedAxisTolerance: 0.10,
requireUniqueDetectedAtMicros: true,
),
// gc_pressure fires above 40 young collections in the 10 s window,
// so 41 is the first count that fires. The at band [41, 61.5] and
// the above band (61.5, 102.5] hold the window count; the count
// climbs from 0 after the leg's reset, so the largest in-span value
// is the leg's steady count. The capture screen exports its own
// count of young collections, hence the 25 % tolerance.
BracketSpec(
stableId: 'gc_pressure',
severityLabel: 'warning',
threshold: 41,
unit: 'gcevents',
coveredThresholds: {'gc_pressure.warning'},
profileCapturePaths: [
'test/validation/captures/gc_pressure/gc_pressure_below.json',
'test/validation/captures/gc_pressure/gc_pressure_at.json',
'test/validation/captures/gc_pressure/gc_pressure_above.json',
],
atTolerance: 0.5,
aboveCeilingMultiplier: 2.5,
observedAxisArgKey: 'scavengeCount',
observedAxisTolerance: 0.25,
observedAxisReduction: 'max',
requireUniqueDetectedAtMicros: true,
requireDetectorTraceRecord: true,
// Every recording point after the crossing writes a record, so a
// leg holds many in-band records.
minInBandSamples: 2,
),
],
);