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
abovecapture's observed magnitude.ProfileCaptureSchema.validateBracketrejects the triad whenaboveObs > threshold * aboveCeilingMultiplier. Defaults to 2.0 schema-side when null. Tighten per-detector when theabovecapture must stay well below an adjacent critical tier threshold (e.g. a 1000 ms warning bracket whoseabovemust 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
atcapture's observed magnitude when bracketing the threshold.ProfileCaptureSchema.validateBracketacceptsat.observedin[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 distinctdetectedAtMicrosarg. 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 fromIssueSeverity.<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 enforcesbelow.observed < threshold,threshold <= at.observed <= threshold * 1.1, andabove.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, emitsslow_request,large_response,request_frequency,http_error_spike, andhigh_frequency_same_path; v0.16.1's reproducer only validatesslow_request, so its metadata pinscoveredStableIds: {'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
reproducerOnlythat raises one family toruntimeVerifiedmust 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'sexpectedMagnitude.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.25allows observed within ±25% of expected). Default0.25absorbs iOSMethodChannelcoalescing 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.
NetworkMonitorcovers 5 stable IDs (slow_request,large_response,request_frequency,http_error_spike,high_frequency_same_path) of which onlyslow_request.warningis backed by on-device captures. Without this field the metadata model forced an all-or-nothing choice: either over-claim by tagging the whole detectorruntimeVerified, or under-claim by holding the whole detector atreproducerOnly.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.
reproducerOnlytests prove the detector reacts correctly to inputs at the boundary;runtimeVerifiedadditionally 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