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:
      '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,
    ),
  ],
);