Files
MeshTerm/meshterm/services/link_quality.py
T
Jean-Pierre MartineauandClaude Opus 4.8 2ec18138a7 Rename project from MeshTools to MeshTerm
Rename the package directory, imports, brand strings, env-var prefixes,
console-script entry point, and the config/data dir (~/.config/meshterm).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-07 19:40:49 -04:00

298 lines
10 KiB
Python

"""Link-quality regression detection against a rolling baseline.
The trace and TX tools already persist every measurement, so a link's *history* is on
disk. This service turns that history into an answer to "is this link worse than it
usually is?" — it splits a target's traces into a recent window and an older baseline,
then flags end-to-end and per-hop metrics that have degraded beyond a threshold (e.g. the
yagi→local hop sitting 6 dB below its 30-day median, or the success rate falling off).
It is pure logic over :class:`~meshterm.core.models.TraceResult` lists, so it runs
identically on live data, replayed history, or the simulator.
"""
from __future__ import annotations
import statistics
from dataclasses import dataclass, field
from typing import Callable, Optional
from ..core.models import LOCAL_DEVICE_LABEL, TraceResult, TraceStats
#: Default SNR drop (dB) from baseline that counts as a regression.
DEFAULT_SNR_DROP_DB = 3.0
#: Default success-rate drop (fraction) from baseline that counts as a regression.
DEFAULT_SUCCESS_DROP = 0.2
#: Traces taken as the "recent" window (the rest form the baseline).
DEFAULT_RECENT_COUNT = 3
#: Minimum baseline traces required before a verdict is trustworthy.
DEFAULT_MIN_BASELINE = 3
NodeResolver = Callable[[Optional[str]], Optional[str]]
@dataclass(slots=True)
class MetricChange:
"""A single metric compared between the baseline and recent windows.
Attributes:
subject: What the metric describes (the target, or a ``a → b`` link).
metric: Human-readable metric name (e.g. ``min SNR``).
kind: ``target`` for an end-to-end metric, ``link`` for one hop.
baseline: The baseline-window value.
recent: The recent-window value.
baseline_n: Number of baseline samples behind ``baseline``.
recent_n: Number of recent samples behind ``recent``.
threshold: The drop magnitude that marks a regression.
regressed: Whether ``recent`` is worse than ``baseline`` past ``threshold``.
"""
subject: str
metric: str
kind: str
baseline: float
recent: float
baseline_n: int
recent_n: int
threshold: float
regressed: bool
@property
def delta(self) -> float:
"""Signed change ``recent - baseline`` (negative means degraded)."""
return self.recent - self.baseline
@property
def severity(self) -> str:
"""``critical`` when the drop is at least twice the threshold, else ``warn``/``ok``."""
if not self.regressed:
return "ok"
return "critical" if -self.delta >= 2 * self.threshold else "warn"
@dataclass(slots=True)
class HealthReport:
"""The link-quality verdict for one target.
Attributes:
target: The trace destination analyzed.
baseline_n: Traces in the baseline window.
recent_n: Traces in the recent window.
changes: Every metric evaluated (target-level and per-link).
"""
target: str
baseline_n: int
recent_n: int
changes: list[MetricChange] = field(default_factory=list)
@property
def regressions(self) -> list[MetricChange]:
"""The subset of ``changes`` that actually regressed, worst drop first."""
return sorted(
(c for c in self.changes if c.regressed), key=lambda c: c.delta
)
@property
def status(self) -> str:
"""``insufficient-data``, ``ok``, ``degraded`` (warn), or ``critical``."""
if not self.changes:
return "insufficient-data"
regs = self.regressions
if not regs:
return "ok"
if any(c.severity == "critical" for c in regs):
return "critical"
return "degraded"
def analyze_target(
target: str,
traces: list[TraceResult],
*,
recent_count: int = DEFAULT_RECENT_COUNT,
min_baseline: int = DEFAULT_MIN_BASELINE,
snr_drop_db: float = DEFAULT_SNR_DROP_DB,
success_drop: float = DEFAULT_SUCCESS_DROP,
resolve: Optional[NodeResolver] = None,
device_label: str = LOCAL_DEVICE_LABEL,
) -> HealthReport:
"""Detect link-quality regressions for ``target`` from its trace history.
The traces are split by recency: the newest ``recent_count`` form the recent window,
the remainder the baseline. End-to-end bottleneck SNR and success rate are compared,
plus the median SNR of each per-hop link that appears in both windows.
Args:
target: The trace destination.
traces: Its trace history (any order; partitioned here by timestamp).
recent_count: Number of newest traces treated as the recent window.
min_baseline: Minimum baseline traces required for a verdict.
snr_drop_db: SNR drop (dB) from baseline that flags a regression.
success_drop: Success-rate drop (fraction) that flags a regression.
resolve: Optional resolver mapping a hop hash to a friendly node name.
device_label: Label for our own device at the path endpoints.
Returns:
A :class:`HealthReport`. With too little history its ``changes`` is empty and
``status`` is ``insufficient-data``.
"""
ordered = sorted(traces, key=lambda t: t.timestamp, reverse=True)
recent = ordered[:recent_count]
baseline = ordered[recent_count:]
if len(recent) < 2 or len(baseline) < min_baseline:
return HealthReport(target=target, baseline_n=len(baseline), recent_n=len(recent))
base_stats = TraceStats.from_traces(target, baseline)
recent_stats = TraceStats.from_traces(target, recent)
changes: list[MetricChange] = []
if base_stats.median_min_snr is not None and recent_stats.median_min_snr is not None:
changes.append(
_change(
subject=target,
metric="min SNR (dB)",
kind="target",
baseline=base_stats.median_min_snr,
recent=recent_stats.median_min_snr,
baseline_n=base_stats.successes,
recent_n=recent_stats.successes,
threshold=snr_drop_db,
)
)
changes.append(
_change(
subject=target,
metric="success rate",
kind="target",
baseline=base_stats.success_rate,
recent=recent_stats.success_rate,
baseline_n=base_stats.samples,
recent_n=recent_stats.samples,
threshold=success_drop,
)
)
changes.extend(
_link_changes(baseline, recent, snr_drop_db, resolve, device_label)
)
return HealthReport(
target=target, baseline_n=len(baseline), recent_n=len(recent), changes=changes
)
def _change(
*,
subject: str,
metric: str,
kind: str,
baseline: float,
recent: float,
baseline_n: int,
recent_n: int,
threshold: float,
) -> MetricChange:
"""Build a :class:`MetricChange`, flagging it regressed on a drop past ``threshold``.
Both metrics here are "higher is better" (SNR, success rate), so a regression is a
decrease of at least ``threshold``.
Args:
subject: What the metric describes.
metric: Metric name.
kind: ``target`` or ``link``.
baseline: Baseline value.
recent: Recent value.
baseline_n: Baseline sample count.
recent_n: Recent sample count.
threshold: Drop magnitude that marks a regression.
Returns:
The populated :class:`MetricChange`.
"""
regressed = (baseline - recent) >= threshold
return MetricChange(
subject=subject,
metric=metric,
kind=kind,
baseline=baseline,
recent=recent,
baseline_n=baseline_n,
recent_n=recent_n,
threshold=threshold,
regressed=regressed,
)
def _link_changes(
baseline: list[TraceResult],
recent: list[TraceResult],
snr_drop_db: float,
resolve: Optional[NodeResolver],
device_label: str,
) -> list[MetricChange]:
"""Compare per-hop link SNR between the two windows.
Only links present in *both* windows are compared, so a transient path that appears
in just one window doesn't masquerade as a regression.
Args:
baseline: Baseline-window traces.
recent: Recent-window traces.
snr_drop_db: SNR drop (dB) that flags a link regression.
resolve: Optional hop-hash → name resolver for the link label.
device_label: Label for our own device.
Returns:
One :class:`MetricChange` per shared link, worst (most negative) drop first.
"""
base_links = _link_snrs(baseline, resolve, device_label)
recent_links = _link_snrs(recent, resolve, device_label)
changes: list[MetricChange] = []
for link in base_links.keys() & recent_links.keys():
base_snrs = base_links[link]
recent_snrs = recent_links[link]
changes.append(
_change(
subject=link,
metric="link SNR (dB)",
kind="link",
baseline=statistics.median(base_snrs),
recent=statistics.median(recent_snrs),
baseline_n=len(base_snrs),
recent_n=len(recent_snrs),
threshold=snr_drop_db,
)
)
return sorted(changes, key=lambda c: c.delta)
def _link_snrs(
traces: list[TraceResult], resolve: Optional[NodeResolver], device_label: str
) -> dict[str, list[float]]:
"""Collect per-link SNR samples keyed by an ``origin → destination`` label.
Args:
traces: The traces to read edges from.
resolve: Optional hop-hash → name resolver.
device_label: Label for our own device at the endpoints.
Returns:
A mapping of link label to the SNR readings seen on it.
"""
out: dict[str, list[float]] = {}
for trace in traces:
if not trace.success:
continue
for edge in trace.edges(device_label):
label = f"{_name(edge.origin, resolve)} → {_name(edge.destination, resolve)}"
out.setdefault(label, []).append(edge.snr)
return out
def _name(label: str, resolve: Optional[NodeResolver]) -> str:
"""Resolve a hop label to a friendly name when a resolver is supplied."""
if resolve is None:
return label
return resolve(label) or label