DetectorMetadata class

Metadata describing how a detector's threshold or heuristic was validated.

Each detector is expected to expose a DetectorMetadata describing the strongest evidence supporting its current numbers. The metadata is surfaced in docs and consumed by the detector_metadata_audit_test.dart CI gate (live since v0.16.1) which walks the SleuthController's registered detector instances and enforces that every shipped detector mixes in DetectorMetadataProvider and returns a non-null metadata entry with a non-empty rationale and tier-appropriate fields (reproducerOnly and above require a reproducerPath; externallyCited requires a citationUrl).

Prefer constructing instances as const so detectors can return them from DetectorMetadataProvider.validationMetadata without allocation at scan time.

Annotations
  • @experimental

Constructors

DetectorMetadata({required EvidenceTier tier, required String rationale, String? citationUrl, String? reproducerPath, List<String>? profileCapturePaths, num? bracketThreshold, String? bracketUnit, String? bracketStableId, String? bracketSeverityLabel, Set<String>? coveredStableIds, Set<String>? parametricFamilies, Map<String, EvidenceTier>? perStableIdTier, Set<String>? coveredThresholds, double? aboveCeilingMultiplier, double? bracketAtTolerance, bool bracketRequireUniqueDetectedAtMicros = false, String? observedAxisArgKey, double observedAxisTolerance = 0.25, String observedAxisReduction = 'max', List<BracketSpec>? additionalBrackets})
const

Properties

aboveCeilingMultiplier → double?
For EvidenceTier.runtimeVerified and above, the upper bound multiplier applied to the above capture's observed magnitude. ProfileCaptureSchema.validateBracket rejects the triad when aboveObs > threshold * aboveCeilingMultiplier. Defaults to 2.0 schema-side when null. Tighten per-detector when the above capture must stay well below an adjacent critical tier threshold (e.g. a 1000 ms warning bracket whose above must stay under the 3000 ms critical to avoid dual-use evidence).
final
additionalBrackets → List<BracketSpec>?
Additional bracket axes for detectors whose runtimeVerified evidence covers more than one independent observable. The top-level bracket fields (bracketStableId, bracketThreshold, bracketUnit, etc.) describe the canonical bracket; each entry in additionalBrackets describes a parallel axis with its own threshold, capture triad, and validation rules.
final
bracketAtTolerance → double?
For EvidenceTier.runtimeVerified and above, the relative tolerance applied to the at capture's observed magnitude when bracketing the threshold. ProfileCaptureSchema.validateBracket accepts at.observed in [threshold, threshold × (1 + bracketAtTolerance)]. Defaults to 0.10 schema-side when null (a 10 % at-band).
final
bracketRequireUniqueDetectedAtMicros → bool
Opt-in stronger schema check (since v0.18.1): when true, every in-span sleuth.issue.<stableId>.<severity> trace record in the at + above captures must carry a distinct detectedAtMicros arg. Rejects single-issue replay (N records all stamped with one microsecond) and pre-v0.18.1 capture binaries that lacked producer-side dedup.
final
bracketSeverityLabel → String?
Severity label ('warning' or 'critical', the wire-format string from IssueSeverity.<label>.name) that the audit gate's trace-record check must match. Required alongside bracketStableId when tier is EvidenceTier.runtimeVerified or stronger.
final
bracketStableId → String?
The stableId whose sleuth.issue.<stableId>.<severity> trace record the audit gate requires inside the at+above captures. Required when tier is EvidenceTier.runtimeVerified or stronger — without it the schema cannot prove the detector actually fired during the captured scenario; the bracket alone proves only that the captured magnitudes flank the threshold, not that the detector reacted.
final
bracketThreshold → num?
For EvidenceTier.runtimeVerified and above, the numeric threshold the three captures in profileCapturePaths are required to bracket. The audit gate calls ProfileCaptureSchema.validateBracket(threshold: bracketThreshold, unit: bracketUnit, ...) on the triad, which enforces below.observed < threshold, threshold <= at.observed <= threshold * 1.1, and above.observed > threshold. Without this field the audit can confirm the three captures exist and parse cleanly but cannot verify the bracketing rule itself — a tier raise could ship with three captures all recorded well below (or well above) the threshold.
final
bracketUnit → String?
Unit label for bracketThreshold (e.g. 'ms', 'bytes', 'frames'). Required alongside bracketThreshold.
final
citationUrl → String?
For EvidenceTier.externallyCited, a URL pointing at the source of truth (Flutter SDK constant, dart-lang issue, published benchmark). Null for tiers below EvidenceTier.externallyCited.
final
coveredStableIds → Set<String>?
The set of stable issue IDs this tier claim covers, for detectors that emit more than one family of issue. NetworkMonitorDetector, for example, emits slow_request, large_response, request_frequency, http_error_spike, and high_frequency_same_path; v0.16.1's reproducer only validates slow_request, so its metadata pins coveredStableIds: {'slow_request'} and the remaining families are implicitly EvidenceTier.unvalidated.
final
coveredThresholds → Set<String>?
Severity-scoped evidence boundaries for detectors that emit multiple severity tiers on the same stable ID. Entries use the form <stableId>.<severity> (e.g. 'slow_request.warning'). When null, the coveredStableIds entries apply to every severity the detector can emit for that family — correct for single-severity detectors but overclaims when a detector has per-severity threshold semantics.
final
effectiveMaxTier → EvidenceTier
The strongest effective tier across the base tier and all perStableIdTier entries. Drives the audit gate's tier-specific field-presence requirements when perStableIdTier is set: a detector at base reproducerOnly that raises one family to runtimeVerified must still satisfy the runtimeVerified field-presence checks (profileCapturePaths, bracketThreshold, etc.).
no setter
hashCode → int
The hash code for this object.
no setterinherited
observedAxisArgKey → String?
Trace-event arg key holding the detector-observed axis value, stamped by the detector via PerformanceIssue.extraTraceArgs (e.g. 'observedCount' for PlatformChannelDetector's frequency axis). When non-null, the audit gate cross-checks the capture's expectedMagnitude.observed (a SEND-side estimate computed by the capture-helper screen) against this trace-event arg using observedAxisTolerance, rejecting captures whose send-side and detector-observed magnitudes diverge enough to cross a bracket band boundary. Null when the detector does not export a cross-checkable observed value (most non-frequency detectors).
final
observedAxisReduction → String
Reduction strategy for selecting a single observed value when observedAxisArgKey cross-check finds multiple in-span trace records.
final
observedAxisTolerance → double
Tolerance for the observedAxisArgKey cross-check, expressed as a fraction of expectedMagnitude.observed (e.g. 0.25 allows observed within ±25% of expected). Default 0.25 absorbs iOS MethodChannel coalescing variance plus parser dedup slack. Tighten when device variance is known to be smaller; loosen for hot/throttled devices. When observedAxisArgKey is null, this value is not consulted; the cross-check is skipped entirely.
final
parametricFamilies → Set<String>?
Underscore-parametric family prefixes. Each entry is a family name without trailing separator; the audit matcher credits emitted stableIds that start with '<family>_' AND have a non-empty suffix.
final
perStableIdTier → Map<String, EvidenceTier>?
Per-family evidence-tier overrides (since v0.18.3). Lets a detector honestly declare a mixed-tier ledger: e.g. NetworkMonitor covers 5 stable IDs (slow_request, large_response, request_frequency, http_error_spike, high_frequency_same_path) of which only slow_request.warning is backed by on-device captures. Without this field the metadata model forced an all-or-nothing choice: either over-claim by tagging the whole detector runtimeVerified, or under-claim by holding the whole detector at reproducerOnly.
final
profileCapturePaths → List<String>?
For EvidenceTier.runtimeVerified and above, repo-relative paths to the checked-in profile-mode captures (timeline JSON, DevTools export, recorded frame batch) that back the claim that the detector's numbers hold against a real engine in profile mode — not only against unit-test stubs driving the detector's inputs directly. reproducerOnly tests prove the detector reacts correctly to inputs at the boundary; runtimeVerified additionally proves those inputs actually occur on a reference device with the claimed magnitude.
final
rationale → String
Human-readable summary of what was validated and how. One or two sentences — full methodology lives in the validation spec doc.
final
reproducerPath → String?
For EvidenceTier.reproducerOnly and above, a repo-relative path to the test or demo that exercises the detector deterministically.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
tier → EvidenceTier
Strongest evidence tier that applies to this detector's numbers.
final

Methods

effectiveTierFor(String stableId, {String? severity}) → EvidenceTier
Returns the effective evidence tier for a specific stable ID, applying any perStableIdTier override on top of the detector's base tier. Returns tier when no override is set.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited