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:
      'Pure Dart and opt-in. `Sleuth.trackResource(name, resource)` '
      'registers a `WeakReference`, a Finalizer token and a first-seen '
      'timestamp. The token is the registration identity '
      '(allocation-unique). A shared `Finalizer` dispatches '
      '`_recordRelease(token)` when the GC reclaims a target, so the '
      'bucket count matches reality without retaining targets. A periodic '
      'sweep (default 10 s) evaluates two thresholds. '
      '`tracked_resource_concurrent.warning` fires when the live count is '
      'above `maxConcurrent` (default 5). '
      '`tracked_resource_long_lived.warning` fires when the oldest '
      'instance is alive past `longLivedSeconds` (default 300). Both have '
      '`confirmed` confidence. An LRU cap (default 1000) bounds the '
      'bucket map, and eviction detaches per-ref Finalizer entries. '
      'Cross-isolate registration is a no-op.\n\n'
      '`tracked_resource_concurrent.warning` is runtimeVerified via '
      '`perStableIdTier` (three iPhone 12, iOS 17.5, Flutter 3.41.4 '
      'captures). The threshold is 6, the smallest count above the '
      'default 5 that triggers emission. atTolerance is 0.5 (the at-band '
      '[6, 9] absorbs discrete-count quantisation), and '
      'aboveCeilingMultiplier is 3.0 (ceiling 18). '
      '`PerformanceIssue.captureTraceStableId` routes parametric '
      '`tracked_resource_concurrent:<name>` emissions to the bare family '
      'so the bracket validator matches every member. The metadata sets '
      '`requireUniqueDetectedAtMicros: true`.\n\n'
      '`tracked_resource_long_lived.warning` is runtimeVerified via '
      '`additionalBrackets[0]` on a separate axis '
      '(`oldestInstanceAgeSeconds`, unit `seconds`). Three iPhone 12, iOS '
      '17.5, Flutter 3.41.4 captures use real waits past the default 300 '
      's threshold. atTolerance is 0.5 (at-band [300, 450]) and '
      'aboveCeilingMultiplier is 3.0 (ceiling 900). The detector re-emits '
      'on each sweep while the age is above the threshold, so the trace '
      'holds an ascending-age series that ends at the leg-end value. '
      'observedAxisReduction `max` therefore picks the leg-end value. The '
      'metadata sets `requireUniqueDetectedAtMicros: true`.',
  reproducerPath: 'test/validation/tracked_resource_reproducer_test.dart',
  coveredStableIds: {concurrentStableId, longLivedStableId},
  coveredThresholds: {'tracked_resource_concurrent.warning'},
  perStableIdTier: {
    concurrentStableId: EvidenceTier.runtimeVerified,
    longLivedStableId: EvidenceTier.runtimeVerified,
  },
  profileCapturePaths: [
    'test/validation/captures/tracked_resource_concurrent/below.json',
    'test/validation/captures/tracked_resource_concurrent/at.json',
    'test/validation/captures/tracked_resource_concurrent/above.json',
  ],
  bracketStableId: concurrentStableId,
  bracketSeverityLabel: 'warning',
  bracketThreshold: 6,
  bracketUnit: 'instances',
  bracketAtTolerance: 0.5,
  aboveCeilingMultiplier: 3.0,
  observedAxisArgKey: 'liveInstanceCount',
  bracketRequireUniqueDetectedAtMicros: true,
  additionalBrackets: [
    BracketSpec(
      stableId: longLivedStableId,
      severityLabel: 'warning',
      threshold: 300,
      unit: 'seconds',
      coveredThresholds: {'tracked_resource_long_lived.warning'},
      profileCapturePaths: [
        'test/validation/captures/tracked_resource_long_lived/below.json',
        'test/validation/captures/tracked_resource_long_lived/at.json',
        'test/validation/captures/tracked_resource_long_lived/above.json',
      ],
      atTolerance: 0.5,
      aboveCeilingMultiplier: 3.0,
      observedAxisArgKey: 'oldestInstanceAgeSeconds',
      requireUniqueDetectedAtMicros: true,
      requireDetectorTraceRecord: true,
    ),
  ],
);