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 inDetectorMetadata.perStableIdTiermust 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 onseverityLabelvalidate disjointsleuth.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 distinctdetectedAtMicrosarg. 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 asIssueSeverity.<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 asleuth.issue.<stableId>.<severityLabel>trace record when requireDetectorTraceRecord is true.final - threshold → num
-
Numeric threshold the capture triad brackets —
below.observed < threshold,at.observedin[threshold, threshold × (1 + atTolerance)],above.observed > threshold(and below theaboveCeilingMultiplierceiling).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