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.
- latency_steps/__init__.py +3 -0
- latency_steps/__main__.py +3 -0
- latency_steps/analysis.py +86 -0
- latency_steps/cli.py +199 -0
- latency_steps/detect.py +290 -0
- latency_steps/errors.py +14 -0
- latency_steps/i18n.py +311 -0
- latency_steps/ingest.py +293 -0
- latency_steps/model.py +141 -0
- latency_steps/render/__init__.py +0 -0
- latency_steps/render/common.py +81 -0
- latency_steps/render/jsonout.py +104 -0
- latency_steps/render/markdown.py +102 -0
- latency_steps/render/svg.py +98 -0
- latency_steps/render/table.py +118 -0
- latency_steps/series.py +61 -0
- latency_steps/stratify.py +204 -0
- latency_steps/synth.py +67 -0
- latency_steps-0.1.1.dist-info/METADATA +288 -0
- latency_steps-0.1.1.dist-info/RECORD +23 -0
- latency_steps-0.1.1.dist-info/WHEEL +4 -0
- latency_steps-0.1.1.dist-info/entry_points.txt +2 -0
- latency_steps-0.1.1.dist-info/licenses/LICENSE +21 -0
|
@@ -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())
|
latency_steps/detect.py
ADDED
|
@@ -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"]
|
latency_steps/errors.py
ADDED
|
@@ -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)
|