pub struct Threshold { /* private fields */ }Expand description
A metric limit that has been checked against the metric’s
Scale: the metric id is known, the limit is finite, and a
ratio-scale limit is non-negative.
Built with Threshold::check. Fields are private so every
Threshold in existence has passed that validation; read them back
through id, info and
limit.
Equality compares the metric id and the limit (f64 ==).
Implementations§
Source§impl Threshold
impl Threshold
Sourcepub fn check(id: &str, limit: f64) -> Result<Checked, LimitError>
pub fn check(id: &str, limit: f64) -> Result<Checked, LimitError>
Validate limit for the metric id.
§Errors
LimitError::UnknownMetricwhenidis not inMETRICS;LimitError::NotFinitefor a NaN or infinite limit;LimitError::Negativefor a negative limit on aScale::Ratiometric.
A Scale::Interval limit outside the domain, or on the domain
edge at the metric’s bad end, is accepted with a
LimitWarning in Checked::warning.
Sourcepub fn info(&self) -> &'static MetricInfo
pub fn info(&self) -> &'static MetricInfo
The catalog entry of the gated metric.
Sourcepub fn warning(&self) -> Option<LimitWarning>
pub fn warning(&self) -> Option<LimitWarning>
The advisory this limit raises, if any: an interval-scale limit
outside its domain, or on the domain edge at the metric’s bad end
where a strict comparison cannot fire. The same advisory
check returns in Checked::warning, asked of a
threshold already in hand — a soft-tier limit
soft_limit derived, say.
Sourcepub fn breaches(&self, v: f64) -> bool
pub fn breaches(&self, v: f64) -> bool
Whether v breaches the limit: strictly greater for a
higher-is-worse metric, strictly less for a lower-is-worse one.
A value equal to the limit does not breach, and NaN never does.
Sourcepub fn excess(&self, v: f64) -> f64
pub fn excess(&self, v: f64) -> f64
The signed distance of v past the limit in the bad direction:
positive for a breach, zero on the limit, negative inside it.
Sourcepub fn severity(&self, v: f64) -> f64
pub fn severity(&self, v: f64) -> f64
How badly v breaches the limit, as a multiple where 1.0 is
“on the limit”. Comparable across metrics, so a ranking of
offenders can sort on it directly.
Scale::Ratioceiling with a positive limit: exactlyv / limit(bitwise; the ratio users already read as “2× over”). A ratio-scale floor, which the catalog has none of today, inverts it tolimit / v.Scale::Ratiowith a zero limit (or a floor breached by a zero value):f64::INFINITY. Every such breach saturates; tie-break onexcess, ascmp_severitydoes.Scale::Interval:1 + excess / unit, one step per unit of badness past the limit. Finite for any finitev, whatever its sign or the limit’s.
Defined for a breaching value. Callers rank only breaches; for a value that does not breach the result is unspecified.
Sourcepub fn cmp_severity(&self, a: f64, b: f64) -> Ordering
pub fn cmp_severity(&self, a: f64, b: f64) -> Ordering
Order two breaching values of this metric: Ordering::Greater
means a is the worse breach. Compares
severity and breaks a tie (including two
saturated zero-limit severities) on excess.
Sourcepub fn cmp_breach(&self, a: f64, other: &Self, b: f64) -> Ordering
pub fn cmp_breach(&self, a: f64, other: &Self, b: f64) -> Ordering
Order the breach a of this threshold against the breach b of
other, which may gate a different metric or limit:
Ordering::Greater means a is the worse breach. The same key
as cmp_severity — severity, then excess —
so a ranking across metrics and a ranking within one agree.
Sourcepub fn is_soft_ratio(ratio: f64) -> bool
pub fn is_soft_ratio(ratio: f64) -> bool
Whether ratio is a soft-tier band soft_limit
accepts: finite and in (0, 1]. 1.0 is the identity; a ratio
above it would make the soft tier looser than the hard gate, and
0, a negative or NaN is a usage error.
Sourcepub fn soft_limit(&self, ratio: f64) -> Result<Self, LimitError>
pub fn soft_limit(&self, ratio: f64) -> Result<Self, LimitError>
The stricter soft-tier threshold for a band ratio in (0, 1].
Scale::Ratio:limit · ratiofor a ceiling,limit / ratiofor a floor.Scale::Interval: the limit moved(1 - ratio) · unitinto the healthy side — up for a floor, down for a ceiling — and clamped at the domain’s healthy edge (maxfor a floor,minfor a ceiling), though never past the hard limit itself, so a soft tier is never looser than its hard tier even for an out-of-domain limit. Multiplying a floor of-50would loosen it, which is why an interval metric cannot share the ratio arithmetic.
ratio == 1 returns the hard threshold unchanged. No rounding is
applied; presentation rounding is the caller’s concern.
§Errors
LimitError::BadRatio when ratio is not finite or lies
outside (0, 1].
Sourcepub fn change(&self, recorded: f64, v: f64) -> Change
pub fn change(&self, recorded: f64, v: f64) -> Change
How v has moved from its baseline recorded value, positive
when worse. A Scale::Ratio metric reports a percentage of the
record (or Change::FromZero for a zero record); a
Scale::Interval metric reports points, since a percentage of
an arbitrary zero is meaningless. A NaN v is Change::NaN.
Sourcepub fn drift(&self, recorded: f64, v: f64) -> f64
pub fn drift(&self, recorded: f64, v: f64) -> f64
A non-negative magnitude of the move from recorded to v. The
ratio form lies in [0, 1]; the interval form counts units and is
unbounded, so a ranking across the two scales favours a large
mi.* move.
Scale::Ratio:|recorded - v| / max(|recorded|, |v|), in[0, 1], and0when both are zero.Scale::Interval:|recorded - v| / unit, so a hundredth of a point near an arbitrary zero stays a hundredth of a step.