BracketSpec class

One bracket axis declaration for a detector's runtimeVerified evidence.

Carries the same per-axis data the top-level bracket fields on DetectorMetadata do — stableId, severityLabel, threshold, unit, at-tolerance, above-ceiling, capture triad, observed-axis cross-check settings, and per-axis schema strictness flags — but as a self-contained const value so a single detector can declare more than one independent bracket via DetectorMetadata.additionalBrackets.

The audit gate validates each spec independently by calling ProfileCaptureSchema.validateBracket once per spec (top-level and each DetectorMetadata.additionalBrackets entry); see the field-level docs on DetectorMetadata.additionalBrackets for the cross-spec invariants (uniqueness on (stableId, severityLabel, observedAxisArgKey), perStableIdTier coverage, orphan-audit iteration).

Annotations
  • @experimental

Constructors

BracketSpec({required String stableId, required String severityLabel, required num threshold, required String unit, required Set<String> coveredThresholds, required List<String> profileCapturePaths, double? atTolerance, double? aboveCeilingMultiplier, String? observedAxisArgKey, double observedAxisTolerance = 0.25, String observedAxisReduction = 'max', bool requireUniqueDetectedAtMicros = false, bool requireDetectorTraceRecord = true, int? minInBandSamples})
const

Properties

aboveCeilingMultiplier → double?
Upper-bound multiplier on the above-leg's observed magnitude. Defaults schema-side to 2.0 when null. Same semantics as DetectorMetadata.aboveCeilingMultiplier.
final
atTolerance → double?
Relative tolerance on the at-leg's observed magnitude. Defaults schema-side to 0.10 when null (10% at-band). Same semantics as DetectorMetadata.bracketAtTolerance.
final
coveredThresholds → Set<String>
<stableId>.<severity> entries this spec is the bracket evidence for. Used by the audit gate's perStableIdTier-coverage check: every runtimeVerified family in DetectorMetadata.perStableIdTier must appear in either the canonical DetectorMetadata.coveredThresholds or in some spec's coveredThresholds.
final
hashCode → int
The hash code for this object.
no setterinherited
minInBandSamples → int?
Minimum count of in-span detector samples per leg whose extraTraceArgs.<observedAxisArgKey> value lies in that leg's role band (at-band for the at-leg capture, above-band for the above-leg capture). Default null = no enforcement.
final
observedAxisArgKey → String?
Trace-event arg key the audit gate cross-checks against the capture's expectedMagnitude.observed. Null skips the cross-check. Same semantics as DetectorMetadata.observedAxisArgKey. Two specs declared on the same (stableId, severityLabel) must use distinct argKeys (or one must be null) — the cross-spec uniqueness invariant on the (stableId, severityLabel, argKey) tuple is what lets multiple bracket axes coexist on a single family + severity without double-counting trace events. Specs that differ on severityLabel validate disjoint sleuth.issue.<id>.<severity> events and never collide regardless of argKey (canonical tier-stack raise pattern).
final
observedAxisReduction → String
Reduction strategy when multiple in-span trace records carry observedAxisArgKey. Same values as DetectorMetadata.observedAxisReduction: 'max' (default, monotone-per-emission axes) or 'last' (windowed-aggregate axes). When observedAxisArgKey is null, this value is not consulted; the cross-check is skipped entirely.
final
observedAxisTolerance → double
Tolerance for the observedAxisArgKey cross-check. Same semantics as DetectorMetadata.observedAxisTolerance. Default 0.25. When observedAxisArgKey is null, this value is not consulted; the cross-check is skipped entirely.
final
profileCapturePaths → List<String>
Repo-relative paths to the three capture files (below / at / above) backing this spec. Always exactly 3 entries — the audit gate's BracketSpec.profileCapturePaths iteration enforces it.
final
requireDetectorTraceRecord → bool
When true, the at + above captures must contain at least one sleuth.issue.<stableId>.<severityLabel> trace record inside the scenario span. Default true — proves the detector actually fired for the captured scenario, closing the bracket-without-emission gap. Set false only for axes whose trace evidence is provided by the canonical bracket alone (rare; the multi-axis pattern usually produces independent emissions per axis).
final
requireUniqueDetectedAtMicros → bool
When true, every in-span sleuth.issue.<stableId>.<severity> trace record in the at + above captures must carry a distinct detectedAtMicros arg. Same semantics as DetectorMetadata.bracketRequireUniqueDetectedAtMicros. Default false; flip to true for v0.18.1+ captures recorded under producer-side dedup.
final
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
severityLabel → String
Severity label ('warning' or 'critical') the bracket targets. Same wire-format string as IssueSeverity.<label>.name.
final
stableId → String
The stable issue ID this spec brackets (e.g. 'platform_channel_traffic'). The capture triad's at + above legs must contain a sleuth.issue.<stableId>.<severityLabel> trace record when requireDetectorTraceRecord is true.
final
threshold → num
Numeric threshold the capture triad brackets — below.observed < threshold, at.observed in [threshold, threshold × (1 + atTolerance)], above.observed > threshold (and below the aboveCeilingMultiplier ceiling).
final
unit → String
Unit label for threshold (must be in ProfileCaptureSchema.approvedUnits, e.g. 'ms', 'bytes/sec', 'percent').
final

Methods

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