latency-steps 0.1.1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,3 @@
1
+ """Find when latency stepped up in raw event logs, then stratify the before/after windows."""
2
+
3
+ __version__ = "0.1.1"
@@ -0,0 +1,3 @@
1
+ from latency_steps.cli import main
2
+
3
+ raise SystemExit(main())
@@ -0,0 +1,86 @@
1
+ """The analysis pipeline: ingest -> percentile series -> steps -> stratification."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+
7
+ from . import __version__
8
+ from .detect import DEFAULT_THRESHOLD, detect_all
9
+ from .errors import LatencyStepsError
10
+ from .ingest import connect, load_events
11
+ from .model import Report
12
+ from .series import build_series, choose_bucket
13
+ from .stratify import parse_dim, stratify_change
14
+
15
+
16
+ @dataclass
17
+ class Options:
18
+ """Everything ``analyze`` needs; defaults match the CLI defaults."""
19
+
20
+ ts: str | None = None
21
+ duration: str | None = None
22
+ duration_unit: str | None = None
23
+ key: str | None = None
24
+ by: list[str] = field(default_factory=list)
25
+ bucket: str = "auto"
26
+ min_n: int = 30
27
+ min_run: int = 3
28
+ min_ratio: float = 1.2
29
+ metric: str = "both"
30
+ tz: str = "UTC"
31
+ only: list[str] = field(default_factory=list)
32
+ memory_limit: str = "1GB"
33
+ threshold: float = DEFAULT_THRESHOLD
34
+
35
+
36
+ def analyze(path: str, opts: Options, *, synthetic: bool = False, label: str | None = None) -> Report:
37
+ """Run the full analysis on ``path`` (``-`` reads standard input)."""
38
+ if opts.min_run < 2:
39
+ raise LatencyStepsError("bad_number", name="--min-run", value=opts.min_run)
40
+ if opts.min_ratio <= 1.0:
41
+ raise LatencyStepsError("bad_number", name="--min-ratio", value=opts.min_ratio)
42
+ if opts.metric not in ("p50", "p90", "both"):
43
+ raise LatencyStepsError("bad_metric", value=opts.metric)
44
+ dims = [parse_dim(spec, i) for i, spec in enumerate(opts.by)]
45
+ con = connect(opts.memory_limit)
46
+ try:
47
+ stats = load_events(
48
+ con,
49
+ path,
50
+ ts_field=opts.ts,
51
+ duration_field=opts.duration,
52
+ duration_unit=opts.duration_unit,
53
+ key_field=opts.key,
54
+ by_fields=[d.field for d in dims],
55
+ tz=opts.tz,
56
+ )
57
+ bucket = choose_bucket(con, opts.bucket)
58
+ series = build_series(con, bucket, opts.min_n, opts.only or None)
59
+ if opts.only and not series:
60
+ raise LatencyStepsError("no_such_key", keys=", ".join(opts.only))
61
+ steps, observations = detect_all(
62
+ series,
63
+ min_run=opts.min_run,
64
+ min_ratio=opts.min_ratio,
65
+ metric=opts.metric,
66
+ threshold=opts.threshold,
67
+ )
68
+ findings = [stratify_change(con, s, dims, min_ratio=opts.min_ratio) for s in steps]
69
+ finally:
70
+ con.close()
71
+ return Report(
72
+ version=__version__,
73
+ source=label or ("<stdin>" if path == "-" else path),
74
+ synthetic=synthetic,
75
+ stats=stats,
76
+ bucket=bucket,
77
+ tz=opts.tz,
78
+ min_n=opts.min_n,
79
+ min_run=opts.min_run,
80
+ min_ratio=opts.min_ratio,
81
+ metric=opts.metric,
82
+ dims=[d.field for d in dims],
83
+ series=series,
84
+ findings=findings,
85
+ observations=observations,
86
+ )
latency_steps/cli.py ADDED
@@ -0,0 +1,199 @@
1
+ """Command line entry point: ``latency-steps analyze|demo``."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import argparse
6
+ import re
7
+ import sys
8
+ import tempfile
9
+ import typing
10
+ from collections.abc import Sequence
11
+ from pathlib import Path
12
+
13
+ from . import __version__
14
+ from .analysis import Options, analyze
15
+ from .errors import LatencyStepsError
16
+ from .i18n import LANGS, resolve_lang, scan_lang_argv, t
17
+ from .model import Report
18
+ from .render.jsonout import render_json
19
+ from .render.markdown import render_markdown
20
+ from .render.svg import render_svg
21
+ from .render.table import render_table
22
+ from .synth import DAYS, write_logs
23
+
24
+ FORMATS = ("table", "md", "svg", "json")
25
+ DEMO_BY = ["host", "concurrency:1-3,4-7,8+"]
26
+ EXIT_OK, EXIT_STEP, EXIT_ERROR = 0, 1, 2
27
+
28
+
29
+ def _formatter(lang: str) -> type[argparse.HelpFormatter]:
30
+ class Formatter(argparse.HelpFormatter):
31
+ def add_usage(self, usage, actions, groups, prefix=None): # type: ignore[no-untyped-def]
32
+ # An explicit empty prefix is used by argparse to build sub-command names.
33
+ return super().add_usage(usage, actions, groups, t(lang, "usage") if prefix is None else prefix)
34
+
35
+ return Formatter
36
+
37
+
38
+ _ARGPARSE_PATTERNS = (
39
+ (r"argument (.+?): invalid choice: (.+?) \(choose from (.+)\)$", "argp.invalid_choice", ("arg", "value", "choices")),
40
+ (r"argument (.+?): invalid (?:int|float) value: (.+)$", "argp.invalid_number", ("arg", "value")),
41
+ (r"argument (.+?): expected one argument$", "argp.expected_one", ("arg",)),
42
+ (r"the following arguments are required: (.+)$", "argp.required", ("names",)),
43
+ (r"unrecognized arguments: (.+)$", "argp.unrecognized", ("names",)),
44
+ )
45
+
46
+
47
+ def translate_argparse_error(lang: str, message: str) -> str:
48
+ """Map the common argparse error texts to the catalog; unknown texts stay as they are."""
49
+ if lang == "en":
50
+ return message
51
+ for regex, key, names in _ARGPARSE_PATTERNS:
52
+ match = re.match(regex, message)
53
+ if match:
54
+ return t(lang, key, **dict(zip(names, match.groups())))
55
+ return message
56
+
57
+
58
+ def _parser_class(lang: str) -> type[argparse.ArgumentParser]:
59
+ class Parser(argparse.ArgumentParser):
60
+ def error(self, message: str) -> typing.NoReturn:
61
+ self.print_usage(sys.stderr)
62
+ text = translate_argparse_error(lang, message)
63
+ self.exit(EXIT_ERROR, f"{self.prog}: {t(lang, 'err.prefix')}: {text}\n")
64
+
65
+ return Parser
66
+
67
+
68
+ def _localize_help(p: argparse.ArgumentParser, lang: str) -> None:
69
+ """Add a translated -h/--help and translate the section titles."""
70
+ p.add_argument("-h", "--help", action="help", default=argparse.SUPPRESS, help=t(lang, "help.help"))
71
+ p._positionals.title = t(lang, "help.positionals") # type: ignore[attr-defined]
72
+ p._optionals.title = t(lang, "help.options") # type: ignore[attr-defined]
73
+
74
+
75
+ def _add_common(p: argparse.ArgumentParser, lang: str) -> None:
76
+ """Options shared by ``analyze`` and ``demo``."""
77
+ p.add_argument("--by", action="append", default=None, metavar="DIM", help=t(lang, "help.by"))
78
+ p.add_argument("--bucket", default="auto", choices=("hour", "day", "auto"), help=t(lang, "help.bucket"))
79
+ p.add_argument("--min-n", type=int, default=30, metavar="N", help=t(lang, "help.min_n"))
80
+ p.add_argument("--min-run", type=int, default=3, metavar="N", help=t(lang, "help.min_run"))
81
+ p.add_argument("--min-ratio", type=float, default=1.2, metavar="X", help=t(lang, "help.min_ratio"))
82
+ p.add_argument("--metric", default="both", choices=("p50", "p90", "both"), help=t(lang, "help.metric"))
83
+ p.add_argument("--tz", default="UTC", metavar="ZONE", help=t(lang, "help.tz"))
84
+ p.add_argument("--only", action="append", default=None, metavar="KEY", help=t(lang, "help.only"))
85
+ p.add_argument("--memory-limit", default="1GB", metavar="SIZE", help=t(lang, "help.memory_limit"))
86
+ p.add_argument("--format", default="table", choices=FORMATS, help=t(lang, "help.format"))
87
+ p.add_argument("--out", default=None, metavar="FILE", help=t(lang, "help.out"))
88
+ p.add_argument("--fail-on-step", action="store_true", help=t(lang, "help.fail_on_step"))
89
+ p.add_argument("--threshold", type=float, default=6.0, help=argparse.SUPPRESS)
90
+ p.add_argument("--lang", choices=LANGS, default=argparse.SUPPRESS, help=t(lang, "help.lang"))
91
+
92
+
93
+ def build_parser(lang: str) -> argparse.ArgumentParser:
94
+ fmt = _formatter(lang)
95
+ cls = _parser_class(lang)
96
+ parser = cls(
97
+ prog="latency-steps", description=t(lang, "help.description"),
98
+ epilog=t(lang, "help.epilog"), formatter_class=fmt, add_help=False,
99
+ )
100
+ _localize_help(parser, lang)
101
+ parser.add_argument("--lang", choices=LANGS, default=None, help=t(lang, "help.lang"))
102
+ parser.add_argument("--version", action="version", version=f"latency-steps {__version__}",
103
+ help=t(lang, "help.version"))
104
+ sub = parser.add_subparsers(dest="command", required=True, parser_class=cls)
105
+
106
+ a = sub.add_parser("analyze", help=t(lang, "help.analyze"), description=t(lang, "help.analyze"),
107
+ epilog=t(lang, "help.epilog"), formatter_class=fmt, add_help=False)
108
+ _localize_help(a, lang)
109
+ a.add_argument("path", help=t(lang, "help.path"))
110
+ a.add_argument("--ts", default=None, metavar="FIELD", help=t(lang, "help.ts"))
111
+ a.add_argument("--duration", default=None, metavar="FIELD", help=t(lang, "help.duration"))
112
+ a.add_argument("--duration-unit", default=None, choices=("ms", "s", "us"), help=t(lang, "help.duration_unit"))
113
+ a.add_argument("--key", default=None, metavar="FIELD", help=t(lang, "help.key"))
114
+ _add_common(a, lang)
115
+
116
+ d = sub.add_parser("demo", help=t(lang, "help.demo"), description=t(lang, "help.demo"),
117
+ epilog=t(lang, "help.epilog"), formatter_class=fmt, add_help=False)
118
+ _localize_help(d, lang)
119
+ d.add_argument("--seed", type=int, default=7, help=t(lang, "help.demo_seed"))
120
+ d.add_argument("--per-hour", type=int, default=40, metavar="N", help=t(lang, "help.demo_per_hour"))
121
+ d.add_argument("--save", default=None, metavar="FILE", help=t(lang, "help.demo_save"))
122
+ _add_common(d, lang)
123
+ return parser
124
+
125
+
126
+ def _options(args: argparse.Namespace, *, demo: bool) -> Options:
127
+ if demo:
128
+ return Options(
129
+ ts="ts", duration="duration_ms", duration_unit="ms", key="tool",
130
+ by=args.by if args.by is not None else list(DEMO_BY), bucket=args.bucket,
131
+ min_n=args.min_n, min_run=args.min_run, min_ratio=args.min_ratio,
132
+ metric=args.metric, tz=args.tz, only=args.only or [],
133
+ memory_limit=args.memory_limit, threshold=args.threshold,
134
+ )
135
+ return Options(
136
+ ts=args.ts, duration=args.duration, duration_unit=args.duration_unit, key=args.key,
137
+ by=args.by or [], bucket=args.bucket, min_n=args.min_n, min_run=args.min_run,
138
+ min_ratio=args.min_ratio, metric=args.metric, tz=args.tz, only=args.only or [],
139
+ memory_limit=args.memory_limit, threshold=args.threshold,
140
+ )
141
+
142
+
143
+ def render(report: Report, fmt: str, lang: str) -> str:
144
+ if fmt == "md":
145
+ return render_markdown(report, lang)
146
+ if fmt == "svg":
147
+ return render_svg(report, lang)
148
+ if fmt == "json":
149
+ return render_json(report, lang)
150
+ return render_table(report, lang)
151
+
152
+
153
+ def _run_demo(args: argparse.Namespace, lang: str) -> Report:
154
+ opts = _options(args, demo=True)
155
+ if args.per_hour < 1:
156
+ raise LatencyStepsError("bad_number", name="--per-hour", value=args.per_hour)
157
+ label = t(lang, "demo.label", seed=args.seed, days=DAYS, per_hour=args.per_hour)
158
+ if args.save:
159
+ write_logs(args.save, args.seed, args.per_hour)
160
+ return analyze(args.save, opts, synthetic=True, label=label)
161
+ with tempfile.TemporaryDirectory(prefix="latency-steps-demo-") as tmp:
162
+ path = Path(tmp) / "demo.jsonl"
163
+ write_logs(path, args.seed, args.per_hour)
164
+ return analyze(str(path), opts, synthetic=True, label=label)
165
+
166
+
167
+ def main(argv: Sequence[str] | None = None) -> int:
168
+ argv = list(sys.argv[1:] if argv is None else argv)
169
+ lang = resolve_lang(scan_lang_argv(argv))
170
+ for stream in (sys.stdout, sys.stderr):
171
+ try:
172
+ stream.reconfigure(encoding="utf-8") # type: ignore[union-attr]
173
+ except (AttributeError, ValueError):
174
+ pass
175
+ parser = build_parser(lang)
176
+ args = parser.parse_args(argv)
177
+ try:
178
+ if args.command == "demo":
179
+ report = _run_demo(args, lang)
180
+ else:
181
+ report = analyze(args.path, _options(args, demo=False))
182
+ text = render(report, args.format, lang)
183
+ if args.out:
184
+ try:
185
+ Path(args.out).write_text(text, encoding="utf-8")
186
+ except OSError as exc:
187
+ raise LatencyStepsError("out_write", path=args.out, reason=exc.strerror or str(exc)) from exc
188
+ else:
189
+ sys.stdout.write(text)
190
+ except LatencyStepsError as exc:
191
+ print(f"{t(lang, 'err.prefix')}: {t(lang, 'err.' + exc.code, **exc.params)}", file=sys.stderr)
192
+ return EXIT_ERROR
193
+ if args.fail_on_step and report.findings:
194
+ return EXIT_STEP
195
+ return EXIT_OK
196
+
197
+
198
+ if __name__ == "__main__":
199
+ raise SystemExit(main())
@@ -0,0 +1,290 @@
1
+ """Step detection on percentile series. Standard library only.
2
+
3
+ The series is analysed on a log scale, so "2x slower" is the same size of
4
+ change at 50 ms and at 5 s. A robust binary segmentation looks for the split
5
+ whose medians differ most relative to the noise (median absolute deviation),
6
+ and recurses on both halves. Medians make a one-bucket spike harmless, which
7
+ is exactly how a *step* (sustained) is told apart from a *spike* (brief).
8
+
9
+ Instead of a penalty value, two numbers you can reason about decide what is
10
+ reported: ``min_run`` (how many buckets the new level must last) and
11
+ ``min_ratio`` (how much slower it must be).
12
+ """
13
+
14
+ from __future__ import annotations
15
+
16
+ import math
17
+ from .model import ChangePoint, KeySeries, Observation
18
+
19
+ DEFAULT_THRESHOLD = 6.0
20
+ SPIKE_Z = 5.0
21
+ NOISE_FLOOR = 0.03 # log units (~3%): never treat smaller wiggles as signal
22
+ COARSE_AFTER = 500 # series longer than this are scanned coarsely first
23
+ MAX_CHANGE_POINTS = 50
24
+
25
+
26
+ def _median(sorted_values: list[float]) -> float:
27
+ n = len(sorted_values)
28
+ mid = n // 2
29
+ if n % 2:
30
+ return sorted_values[mid]
31
+ return 0.5 * (sorted_values[mid - 1] + sorted_values[mid])
32
+
33
+
34
+ def _med(values: list[float]) -> float:
35
+ return _median(sorted(values))
36
+
37
+
38
+ def _mad(values: list[float], center: float) -> float:
39
+ return _med([abs(v - center) for v in values]) * 1.4826
40
+
41
+
42
+ def _noise_floor(y: list[float]) -> float:
43
+ """Robust noise scale of a whole series from successive differences."""
44
+ if len(y) < 3:
45
+ return NOISE_FLOOR
46
+ diffs = [abs(b - a) for a, b in zip(y, y[1:])]
47
+ return max(NOISE_FLOOR, 0.7 * _med(diffs) * 1.4826 / math.sqrt(2))
48
+
49
+
50
+ def _split_stat(y: list[float], k: int, floor: float) -> float:
51
+ left, right = y[:k], y[k:]
52
+ ml, mr = _med(left), _med(right)
53
+ pooled = _med([abs(v - ml) for v in left] + [abs(v - mr) for v in right]) * 1.4826
54
+ scale = max(pooled, floor)
55
+ return (mr - ml) / scale * math.sqrt(len(left) * len(right) / len(y))
56
+
57
+
58
+ def _best_split(y: list[float], min_size: int, floor: float) -> tuple[float, int]:
59
+ """Return (signed statistic, split index) of the strongest split, (0, -1) if none."""
60
+ n = len(y)
61
+ candidates = range(min_size, n - min_size + 1)
62
+ if n > COARSE_AFTER:
63
+ stride = max(1, n // 200)
64
+ coarse = list(range(min_size, n - min_size + 1, stride))
65
+ best = max(coarse, key=lambda k: abs(_split_stat(y, k, floor)))
66
+ candidates = range(max(min_size, best - stride), min(n - min_size, best + stride) + 1)
67
+ best_k, best_stat = -1, 0.0
68
+ for k in candidates:
69
+ stat = _split_stat(y, k, floor)
70
+ if abs(stat) > abs(best_stat):
71
+ best_k, best_stat = k, stat
72
+ return best_stat, best_k
73
+
74
+
75
+ def _refine(y: list[float], k: int, min_size: int, radius: int = 3) -> int:
76
+ """Move a split to the nearby index with the smallest total absolute deviation.
77
+
78
+ The medians barely change when one boundary bucket moves across the split,
79
+ so the strongest-statistic split can be a bucket or two off the real edge.
80
+ """
81
+ n = len(y)
82
+
83
+ def cost(j: int) -> float:
84
+ left, right = y[:j], y[j:]
85
+ ml, mr = _med(left), _med(right)
86
+ return sum(abs(v - ml) for v in left) + sum(abs(v - mr) for v in right)
87
+
88
+ options = range(max(min_size, k - radius), min(n - min_size, k + radius) + 1)
89
+ return min(options, key=cost)
90
+
91
+
92
+ def binary_segmentation(
93
+ y: list[float], min_size: int, threshold: float = DEFAULT_THRESHOLD
94
+ ) -> list[tuple[int, float]]:
95
+ """Return sorted ``(split index, signed statistic)`` pairs for a series ``y``."""
96
+ floor = _noise_floor(y)
97
+ found: list[tuple[int, float]] = []
98
+ stack = [(0, len(y))]
99
+ while stack and len(found) < MAX_CHANGE_POINTS:
100
+ lo, hi = stack.pop()
101
+ if hi - lo < 2 * min_size:
102
+ continue
103
+ stat, k = _best_split(y[lo:hi], min_size, floor)
104
+ if k < 0 or abs(stat) < threshold:
105
+ continue
106
+ k = _refine(y[lo:hi], k, min_size)
107
+ found.append((lo + k, stat))
108
+ stack.append((lo, lo + k))
109
+ stack.append((lo + k, hi))
110
+ return sorted(found)
111
+
112
+
113
+ def _merge(
114
+ per_metric: dict[str, list[tuple[int, float]]], window: int
115
+ ) -> list[tuple[int, float, str]]:
116
+ """Merge change points of the p50 and p90 series that sit within ``window`` buckets."""
117
+ flat = sorted(
118
+ ((idx, stat, metric) for metric, cps in per_metric.items() for idx, stat in cps),
119
+ key=lambda t: t[0],
120
+ )
121
+ groups: list[list[tuple[int, float, str]]] = []
122
+ for item in flat:
123
+ if groups and item[0] - groups[-1][-1][0] <= window and (item[1] > 0) == (groups[-1][-1][1] > 0):
124
+ groups[-1].append(item)
125
+ else:
126
+ groups.append([item])
127
+ # The strongest member represents the group.
128
+ return [max(g, key=lambda t: abs(t[1])) for g in groups]
129
+
130
+
131
+ def _persistent(
132
+ merged: list[tuple[int, float, str]], logs: dict[str, list[float]], n: int, min_run: int
133
+ ) -> list[tuple[int, float, str]]:
134
+ """Drop split points where either side has fewer than ``min_run`` buckets at its own level.
135
+
136
+ A split next to a brief blip can look like a step because the segment must
137
+ hold ``min_run`` points; this checks the points really sit at that level.
138
+ """
139
+ current = list(merged)
140
+ while True:
141
+ edges = [0, *[c[0] for c in current], n]
142
+ bad = None
143
+ for i, (idx, _, metric) in enumerate(current):
144
+ y = logs[metric]
145
+ before, after = y[edges[i]:idx], y[idx:edges[i + 2]]
146
+ mb, ma = _med(before), _med(after)
147
+ near_before = sum(abs(v - mb) < abs(v - ma) for v in before)
148
+ near_after = sum(abs(v - ma) < abs(v - mb) for v in after)
149
+ if min(near_before, near_after) < min_run:
150
+ bad = i
151
+ break
152
+ if bad is None:
153
+ return current
154
+ del current[bad]
155
+
156
+
157
+ def _segments(boundaries: list[int], n: int) -> list[tuple[int, int]]:
158
+ edges = [0, *boundaries, n]
159
+ return list(zip(edges[:-1], edges[1:]))
160
+
161
+
162
+ def detect(
163
+ series: KeySeries,
164
+ *,
165
+ min_run: int = 3,
166
+ min_ratio: float = 1.2,
167
+ metric: str = "both",
168
+ threshold: float = DEFAULT_THRESHOLD,
169
+ ) -> tuple[list[ChangePoint], list[Observation]]:
170
+ """Find sustained steps and brief deviations in one key's series.
171
+
172
+ Returns ``(steps, observations)``. A step is reported only when the new
173
+ level lasts at least ``min_run`` buckets and p50 or p90 changed by at least
174
+ ``min_ratio`` (up). Faster steps and brief or trailing deviations come back
175
+ as observations.
176
+ """
177
+ pts = series.points
178
+ n = len(pts)
179
+ if n < 2 * min_run:
180
+ return [], []
181
+ metrics = ("p50", "p90") if metric == "both" else (metric,)
182
+ logs = {m: [math.log(max(getattr(p, m), 1e-9)) for p in pts] for m in metrics}
183
+
184
+ per_metric = {m: binary_segmentation(logs[m], min_run, threshold) for m in metrics}
185
+ merged = _persistent(_merge(per_metric, min_run), logs, n, min_run)
186
+ boundaries = [idx for idx, _, _ in merged]
187
+ segs = _segments(boundaries, n)
188
+
189
+ steps: list[ChangePoint] = []
190
+ observations: list[Observation] = []
191
+ for i, (idx, stat, _) in enumerate(merged):
192
+ (b_lo, b_hi), (a_lo, a_hi) = segs[i], segs[i + 1]
193
+ ratios: dict[str, float] = {}
194
+ levels: dict[str, tuple[float, float]] = {}
195
+ for m in ("p50", "p90"):
196
+ ylog = [math.log(max(getattr(p, m), 1e-9)) for p in pts]
197
+ before = math.exp(_med(ylog[b_lo:b_hi]))
198
+ after = math.exp(_med(ylog[a_lo:a_hi]))
199
+ levels[m] = (before, after)
200
+ ratios[m] = after / before
201
+ up = stat > 0
202
+ pool = metrics if metric != "both" else ("p50", "p90")
203
+ pick = max(pool, key=lambda m: ratios[m]) if up else min(pool, key=lambda m: ratios[m])
204
+ ratio = ratios[pick]
205
+ at = pts[idx].bucket
206
+ if up and ratio >= min_ratio:
207
+ steps.append(
208
+ ChangePoint(
209
+ key=series.key, index=idx, at=at, direction="up", metric=pick,
210
+ score=round(abs(stat), 2),
211
+ p50_before=levels["p50"][0], p50_after=levels["p50"][1],
212
+ p90_before=levels["p90"][0], p90_after=levels["p90"][1],
213
+ ratio=ratio, run_buckets=a_hi - a_lo,
214
+ before_start=pts[b_lo].bucket,
215
+ after_end=pts[a_hi].bucket if a_hi < n else None,
216
+ )
217
+ )
218
+ elif not up and ratio <= 1 / min_ratio:
219
+ observations.append(
220
+ Observation(series.key, "faster", at, at, pick, ratio)
221
+ )
222
+
223
+ observations.extend(_spikes(series, logs, segs, min_run, min_ratio))
224
+ observations.sort(key=lambda o: (o.at, o.kind))
225
+ return steps, observations
226
+
227
+
228
+ def _spikes(
229
+ series: KeySeries,
230
+ logs: dict[str, list[float]],
231
+ segs: list[tuple[int, int]],
232
+ min_run: int,
233
+ min_ratio: float,
234
+ ) -> list[Observation]:
235
+ """Brief deviations (fewer than ``min_run`` buckets) from the level of their segment."""
236
+ pts = series.points
237
+ n = len(pts)
238
+ floor = _noise_floor(next(iter(logs.values())))
239
+ flagged: dict[int, tuple[str, float]] = {}
240
+ for m, y in logs.items():
241
+ for lo, hi in segs:
242
+ if hi - lo < 5:
243
+ continue
244
+ seg = y[lo:hi]
245
+ center = _med(seg)
246
+ scale = max(_mad(seg, center), floor)
247
+ for j in range(lo, hi):
248
+ dev = y[j] - center
249
+ if abs(dev) / scale > SPIKE_Z and abs(dev) >= math.log(min_ratio):
250
+ prev = flagged.get(j)
251
+ if prev is None or abs(dev) > abs(math.log(prev[1])):
252
+ flagged[j] = (m, math.exp(dev))
253
+ out: list[Observation] = []
254
+ j = 0
255
+ order = sorted(flagged)
256
+ while j < len(order):
257
+ start = order[j]
258
+ end = start
259
+ sign = flagged[start][1] > 1
260
+ while j + 1 < len(order) and order[j + 1] == end + 1 and (flagged[order[j + 1]][1] > 1) == sign:
261
+ j += 1
262
+ end = order[j]
263
+ j += 1
264
+ length = end - start + 1
265
+ if not sign:
266
+ continue # brief speed-ups are not interesting
267
+ if end == n - 1:
268
+ kind = "tail"
269
+ elif length < min_run:
270
+ kind = "spike"
271
+ else:
272
+ continue
273
+ top = max(range(start, end + 1), key=lambda t: flagged[t][1])
274
+ out.append(Observation(series.key, kind, pts[start].bucket, pts[end].bucket, flagged[top][0], flagged[top][1]))
275
+ return out
276
+
277
+
278
+ def detect_all(
279
+ all_series: list[KeySeries], **kwargs: object
280
+ ) -> tuple[list[ChangePoint], list[Observation]]:
281
+ steps: list[ChangePoint] = []
282
+ observations: list[Observation] = []
283
+ for s in all_series:
284
+ st, ob = detect(s, **kwargs) # type: ignore[arg-type]
285
+ steps.extend(st)
286
+ observations.extend(ob)
287
+ return steps, observations
288
+
289
+
290
+ __all__ = ["binary_segmentation", "detect", "detect_all"]
@@ -0,0 +1,14 @@
1
+ """Errors carrying a message code and parameters so the CLI can translate them."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+
8
+ class LatencyStepsError(Exception):
9
+ """A user-fixable problem (bad input, bad option). The CLI maps it to exit code 2."""
10
+
11
+ def __init__(self, code: str, **params: Any) -> None:
12
+ self.code = code
13
+ self.params = params
14
+ super().__init__(f"{code}: {params}" if params else code)