apipulse 0.1.1__tar.gz

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.
apipulse-0.1.1/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Athina09
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,153 @@
1
+ Metadata-Version: 2.4
2
+ Name: apipulse
3
+ Version: 0.1.1
4
+ Summary: A health tracker for the APIs your app depends on: raw-socket probes, per-phase timings, history and diagnosis.
5
+ Author: Athina09
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/Athina09/apipulse
8
+ Project-URL: Issues, https://github.com/Athina09/apipulse/issues
9
+ Keywords: api,monitoring,http,latency,troubleshooting,sockets
10
+ Classifier: Development Status :: 3 - Alpha
11
+ Classifier: Environment :: Console
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Programming Language :: Python :: 3
14
+ Classifier: Topic :: System :: Monitoring
15
+ Classifier: Topic :: Internet :: WWW/HTTP
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # apipulse
22
+
23
+ [![tests](https://github.com/Athina09/apipulse/actions/workflows/tests.yml/badge.svg)](https://github.com/Athina09/apipulse/actions/workflows/tests.yml)
24
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
25
+
26
+ **A health tracker for the APIs your app depends on.**
27
+
28
+ apipulse probes an HTTP API over raw sockets, times every phase of the request
29
+ (DNS, TCP connect, TLS, time to first byte), keeps the history in SQLite, and tells
30
+ you in plain language what looks wrong, including *which part* of the request got slower.
31
+
32
+ - Standard library only: no dependencies to install.
33
+ - Works on any `http://` or `https://` URL, including `localhost` and IPv6.
34
+ - Built as a learning project on sockets and HTTP internals, so the code is small and readable.
35
+
36
+ ![A healthy API](docs/healthy.svg)
37
+
38
+ ## Install
39
+
40
+ Requires Python 3.10 or newer.
41
+
42
+ ```bash
43
+ pipx install git+https://github.com/Athina09/apipulse
44
+ # or: pip install git+https://github.com/Athina09/apipulse
45
+ ```
46
+
47
+ Or run it straight from a clone, with no install:
48
+
49
+ ```bash
50
+ git clone https://github.com/Athina09/apipulse
51
+ cd apipulse
52
+ python3 -m apipulse --help
53
+ ```
54
+
55
+ ## Quick start
56
+
57
+ ```bash
58
+ apipulse watch http://127.0.0.1:3000/ --count 20 --interval 1 --max-latency-ms 200
59
+ apipulse report http://127.0.0.1:3000/
60
+ apipulse diagnose http://127.0.0.1:3000/
61
+ ```
62
+
63
+ | Command | What it does |
64
+ |---|---|
65
+ | `watch <url>` | Probes repeatedly, saves every result, flags slow or failing probes as it goes. |
66
+ | `report <url>` | Prints min, p50, p95 and max latency from the saved history. |
67
+ | `diagnose <url>` | Reads the history and explains what looks wrong. |
68
+
69
+ Useful options for `watch`: `--count N`, `--interval SECONDS`, `--max-latency-ms MS`,
70
+ and `-H 'Name: value'` (repeatable). History is stored in `apipulse.db` in the current
71
+ folder; use `--db PATH` to keep one file per project.
72
+
73
+ ### Probing an API that needs a token
74
+
75
+ ```bash
76
+ apipulse watch https://api.example.com/health -H "Authorization: Bearer $API_TOKEN"
77
+ ```
78
+
79
+ Headers are sent but **never saved** to the history, and error messages never echo
80
+ their values. Pass tokens through an environment variable, as above, so they don't
81
+ end up in your shell history.
82
+
83
+ ## What `diagnose` can tell you
84
+
85
+ ![Finding what went wrong](docs/troubleshooting.svg)
86
+
87
+ | Finding | Meaning |
88
+ |---|---|
89
+ | `critical` / `warning` failures | Connection errors or 5xx responses, with the latest error. 50% or more failing is critical. |
90
+ | 4xx responses | Usually a wrong URL or missing credentials, not an outage. |
91
+ | Inconsistent latency | p95 is more than 3x the p50. |
92
+ | Slowed down | The recent median is more than 2x the older median, **and it names the phase that grew**: DNS, TCP connect, TLS, or server processing time. |
93
+
94
+ Exit codes make it scriptable: `0` ok, `1` warning, `2` critical, `3` bad input.
95
+
96
+ ```bash
97
+ apipulse diagnose http://127.0.0.1:3000/ || echo "needs attention"
98
+ ```
99
+
100
+ ## Try it without a real API
101
+
102
+ The repo includes a small C++ HTTP server (raw sockets) that misbehaves on demand.
103
+
104
+ ```bash
105
+ g++ -std=c++17 -Wall -Wextra testserver/server.cpp -o server
106
+ ./server # listens on 127.0.0.1:8080; Ctrl-C to stop
107
+ ```
108
+
109
+ | Endpoint | Behaviour |
110
+ |---|---|
111
+ | `/` | 200 |
112
+ | `/status/<code>` | Responds with that status code (100-599) |
113
+ | `/delay/<ms>` | Waits, then 200 (capped at 10 seconds) |
114
+
115
+ It handles one client at a time, so a slow request delays the next one.
116
+
117
+ ## How it works
118
+
119
+ ```
120
+ apipulse/
121
+ probe.py one GET over a raw socket, timed by phase
122
+ monitor.py percentiles and repeated probing
123
+ store.py SQLite history (frozen dataclass records)
124
+ diagnose.py rule-based findings
125
+ cli.py the `apipulse` command
126
+ testserver/ the C++ test server
127
+ tests/ unit tests
128
+ ```
129
+
130
+ A probe resolves the name, tries each address in turn (so `localhost` works whether
131
+ the server listens on IPv4 or IPv6), connects, optionally wraps the socket in TLS,
132
+ sends a hand-built `GET` request with `Connection: close`, and reads until the server
133
+ hangs up. Each step is timed with `time.perf_counter()`.
134
+
135
+ ## Limitations
136
+
137
+ - `GET` only. No redirects, and chunked response bodies are read correctly but their
138
+ `body_bytes` count includes the chunk framing.
139
+ - `diagnose` is rule-based. It cannot see a steadily slow API as a problem; use
140
+ `watch --max-latency-ms` to flag that.
141
+ - The test server handles one client at a time.
142
+
143
+ ## Development
144
+
145
+ ```bash
146
+ python3 -m unittest discover -s tests -t . -v
147
+ ```
148
+
149
+ Contributions and bug reports are welcome. Open an issue or a pull request.
150
+
151
+ ## License
152
+
153
+ [MIT](LICENSE)
@@ -0,0 +1,133 @@
1
+ # apipulse
2
+
3
+ [![tests](https://github.com/Athina09/apipulse/actions/workflows/tests.yml/badge.svg)](https://github.com/Athina09/apipulse/actions/workflows/tests.yml)
4
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
5
+
6
+ **A health tracker for the APIs your app depends on.**
7
+
8
+ apipulse probes an HTTP API over raw sockets, times every phase of the request
9
+ (DNS, TCP connect, TLS, time to first byte), keeps the history in SQLite, and tells
10
+ you in plain language what looks wrong, including *which part* of the request got slower.
11
+
12
+ - Standard library only: no dependencies to install.
13
+ - Works on any `http://` or `https://` URL, including `localhost` and IPv6.
14
+ - Built as a learning project on sockets and HTTP internals, so the code is small and readable.
15
+
16
+ ![A healthy API](docs/healthy.svg)
17
+
18
+ ## Install
19
+
20
+ Requires Python 3.10 or newer.
21
+
22
+ ```bash
23
+ pipx install git+https://github.com/Athina09/apipulse
24
+ # or: pip install git+https://github.com/Athina09/apipulse
25
+ ```
26
+
27
+ Or run it straight from a clone, with no install:
28
+
29
+ ```bash
30
+ git clone https://github.com/Athina09/apipulse
31
+ cd apipulse
32
+ python3 -m apipulse --help
33
+ ```
34
+
35
+ ## Quick start
36
+
37
+ ```bash
38
+ apipulse watch http://127.0.0.1:3000/ --count 20 --interval 1 --max-latency-ms 200
39
+ apipulse report http://127.0.0.1:3000/
40
+ apipulse diagnose http://127.0.0.1:3000/
41
+ ```
42
+
43
+ | Command | What it does |
44
+ |---|---|
45
+ | `watch <url>` | Probes repeatedly, saves every result, flags slow or failing probes as it goes. |
46
+ | `report <url>` | Prints min, p50, p95 and max latency from the saved history. |
47
+ | `diagnose <url>` | Reads the history and explains what looks wrong. |
48
+
49
+ Useful options for `watch`: `--count N`, `--interval SECONDS`, `--max-latency-ms MS`,
50
+ and `-H 'Name: value'` (repeatable). History is stored in `apipulse.db` in the current
51
+ folder; use `--db PATH` to keep one file per project.
52
+
53
+ ### Probing an API that needs a token
54
+
55
+ ```bash
56
+ apipulse watch https://api.example.com/health -H "Authorization: Bearer $API_TOKEN"
57
+ ```
58
+
59
+ Headers are sent but **never saved** to the history, and error messages never echo
60
+ their values. Pass tokens through an environment variable, as above, so they don't
61
+ end up in your shell history.
62
+
63
+ ## What `diagnose` can tell you
64
+
65
+ ![Finding what went wrong](docs/troubleshooting.svg)
66
+
67
+ | Finding | Meaning |
68
+ |---|---|
69
+ | `critical` / `warning` failures | Connection errors or 5xx responses, with the latest error. 50% or more failing is critical. |
70
+ | 4xx responses | Usually a wrong URL or missing credentials, not an outage. |
71
+ | Inconsistent latency | p95 is more than 3x the p50. |
72
+ | Slowed down | The recent median is more than 2x the older median, **and it names the phase that grew**: DNS, TCP connect, TLS, or server processing time. |
73
+
74
+ Exit codes make it scriptable: `0` ok, `1` warning, `2` critical, `3` bad input.
75
+
76
+ ```bash
77
+ apipulse diagnose http://127.0.0.1:3000/ || echo "needs attention"
78
+ ```
79
+
80
+ ## Try it without a real API
81
+
82
+ The repo includes a small C++ HTTP server (raw sockets) that misbehaves on demand.
83
+
84
+ ```bash
85
+ g++ -std=c++17 -Wall -Wextra testserver/server.cpp -o server
86
+ ./server # listens on 127.0.0.1:8080; Ctrl-C to stop
87
+ ```
88
+
89
+ | Endpoint | Behaviour |
90
+ |---|---|
91
+ | `/` | 200 |
92
+ | `/status/<code>` | Responds with that status code (100-599) |
93
+ | `/delay/<ms>` | Waits, then 200 (capped at 10 seconds) |
94
+
95
+ It handles one client at a time, so a slow request delays the next one.
96
+
97
+ ## How it works
98
+
99
+ ```
100
+ apipulse/
101
+ probe.py one GET over a raw socket, timed by phase
102
+ monitor.py percentiles and repeated probing
103
+ store.py SQLite history (frozen dataclass records)
104
+ diagnose.py rule-based findings
105
+ cli.py the `apipulse` command
106
+ testserver/ the C++ test server
107
+ tests/ unit tests
108
+ ```
109
+
110
+ A probe resolves the name, tries each address in turn (so `localhost` works whether
111
+ the server listens on IPv4 or IPv6), connects, optionally wraps the socket in TLS,
112
+ sends a hand-built `GET` request with `Connection: close`, and reads until the server
113
+ hangs up. Each step is timed with `time.perf_counter()`.
114
+
115
+ ## Limitations
116
+
117
+ - `GET` only. No redirects, and chunked response bodies are read correctly but their
118
+ `body_bytes` count includes the chunk framing.
119
+ - `diagnose` is rule-based. It cannot see a steadily slow API as a problem; use
120
+ `watch --max-latency-ms` to flag that.
121
+ - The test server handles one client at a time.
122
+
123
+ ## Development
124
+
125
+ ```bash
126
+ python3 -m unittest discover -s tests -t . -v
127
+ ```
128
+
129
+ Contributions and bug reports are welcome. Open an issue or a pull request.
130
+
131
+ ## License
132
+
133
+ [MIT](LICENSE)
@@ -0,0 +1,3 @@
1
+ """apipulse: a health tracker for the APIs your application depends on."""
2
+
3
+ __version__ = "0.1.1"
@@ -0,0 +1,5 @@
1
+ import sys
2
+
3
+ from .cli import main
4
+
5
+ sys.exit(main())
@@ -0,0 +1,168 @@
1
+ """apipulse CLI: watch an API, keep its history, report and diagnose.
2
+
3
+ apipulse watch <url> [--count N] [--interval S] [--max-latency-ms MS] [-H 'Name: value']
4
+ apipulse report <url>
5
+ apipulse diagnose <url>
6
+ """
7
+
8
+ import argparse
9
+ import sys
10
+ import time
11
+ from contextlib import closing
12
+ from typing import Mapping
13
+ from urllib.parse import urlsplit
14
+
15
+ from .diagnose import diagnose, worst_severity
16
+ from .monitor import CLIENT_ERROR_STATUS, percentile
17
+ from .probe import probe, validate_headers
18
+ from .store import DEFAULT_DB_PATH, ProbeRecord, load_recent, open_db, save
19
+
20
+ DEFAULT_COUNT = 10
21
+ DEFAULT_INTERVAL_SECONDS = 1.0
22
+ DEFAULT_HISTORY_LIMIT = 50
23
+
24
+ EXIT_OK = 0
25
+ EXIT_WARNING = 1
26
+ EXIT_CRITICAL = 2
27
+ EXIT_BAD_INPUT = 3
28
+ SEVERITY_EXIT = {"info": EXIT_OK, "warning": EXIT_WARNING, "critical": EXIT_CRITICAL}
29
+
30
+
31
+ def _is_http_url(url: str) -> bool:
32
+ parts = urlsplit(url)
33
+ return parts.scheme in ("http", "https") and bool(parts.hostname)
34
+
35
+
36
+ def _probe_record(url: str, headers: Mapping[str, str]) -> ProbeRecord:
37
+ now = time.time()
38
+ try:
39
+ return ProbeRecord.from_result(probe(url, headers=headers), now)
40
+ except (OSError, ValueError) as error: # unreachable, timeout, TLS or garbled response
41
+ return ProbeRecord.from_error(url, error, now)
42
+
43
+
44
+ def _format_record(record: ProbeRecord, max_latency_ms: float | None) -> str:
45
+ if record.error:
46
+ return f"FAIL {record.error}"
47
+ flags = []
48
+ if record.is_failure:
49
+ flags.append("server error")
50
+ elif record.status_code >= CLIENT_ERROR_STATUS:
51
+ flags.append("client error: check the URL or auth")
52
+ if max_latency_ms is not None and record.total_ms > max_latency_ms:
53
+ flags.append(f"slower than {max_latency_ms:g} ms")
54
+ tag = "ALERT " if flags else "ok "
55
+ line = (
56
+ f"{tag} {record.status_code} total={record.total_ms:.1f} ms "
57
+ f"ttfb={record.ttfb_ms:.1f} ms"
58
+ )
59
+ return f"{line} [{', '.join(flags)}]" if flags else line
60
+
61
+
62
+ def cmd_watch(args: argparse.Namespace) -> int:
63
+ headers = dict(args.header)
64
+ try:
65
+ validate_headers(headers)
66
+ except ValueError as error:
67
+ print(f"bad header: {error}", file=sys.stderr)
68
+ return EXIT_BAD_INPUT
69
+
70
+ saw_problem = False
71
+ with closing(open_db(args.db)) as connection:
72
+ try:
73
+ for attempt in range(args.count):
74
+ if attempt > 0:
75
+ time.sleep(args.interval)
76
+ record = _probe_record(args.url, headers)
77
+ save(connection, record)
78
+ saw_problem = saw_problem or record.is_failure
79
+ print(_format_record(record, args.max_latency_ms))
80
+ except KeyboardInterrupt:
81
+ print("stopped")
82
+ return EXIT_WARNING if saw_problem else EXIT_OK
83
+
84
+
85
+ def cmd_report(args: argparse.Namespace) -> int:
86
+ with closing(open_db(args.db)) as connection:
87
+ records = load_recent(connection, args.url, args.limit)
88
+ if not records:
89
+ print(f"no history for {args.url}")
90
+ return EXIT_OK
91
+
92
+ latencies = sorted(r.total_ms for r in records if r.total_ms is not None)
93
+ failed = sum(1 for r in records if r.is_failure)
94
+ print(f"{args.url}: last {len(records)} probes, {failed} failed")
95
+ if latencies:
96
+ print(f" min {latencies[0]:.2f} ms")
97
+ print(f" p50 {percentile(latencies, 0.50):.2f} ms")
98
+ print(f" p95 {percentile(latencies, 0.95):.2f} ms")
99
+ print(f" max {latencies[-1]:.2f} ms")
100
+ else:
101
+ print(" no successful responses")
102
+ return EXIT_OK
103
+
104
+
105
+ def cmd_diagnose(args: argparse.Namespace) -> int:
106
+ with closing(open_db(args.db)) as connection:
107
+ records = load_recent(connection, args.url, args.limit)
108
+ findings = diagnose(records)
109
+ for finding in findings:
110
+ print(f"[{finding.severity.upper()}] {finding.message}")
111
+ return SEVERITY_EXIT[worst_severity(findings)]
112
+
113
+
114
+ def _header(text: str) -> tuple[str, str]:
115
+ name, separator, value = text.partition(":")
116
+ if not separator or not name.strip():
117
+ # deliberately not echoing `text`: it may contain a token
118
+ raise argparse.ArgumentTypeError("expected 'Name: value'")
119
+ return name.strip(), value.strip()
120
+
121
+
122
+ def _positive_int(text: str) -> int:
123
+ value = int(text)
124
+ if value < 1:
125
+ raise argparse.ArgumentTypeError("must be at least 1")
126
+ return value
127
+
128
+
129
+ def build_parser() -> argparse.ArgumentParser:
130
+ parser = argparse.ArgumentParser(prog="apipulse", description="API health tracker.")
131
+ commands = parser.add_subparsers(dest="command", required=True)
132
+
133
+ def add_common(sub: argparse.ArgumentParser) -> None:
134
+ sub.add_argument("url")
135
+ sub.add_argument("--db", default=DEFAULT_DB_PATH, help="SQLite history file")
136
+
137
+ watch = commands.add_parser("watch", help="probe repeatedly and save results")
138
+ add_common(watch)
139
+ watch.add_argument("--count", type=_positive_int, default=DEFAULT_COUNT)
140
+ watch.add_argument("--interval", type=float, default=DEFAULT_INTERVAL_SECONDS)
141
+ watch.add_argument("--max-latency-ms", type=float, default=None,
142
+ help="flag probes slower than this")
143
+ watch.add_argument("-H", "--header", action="append", type=_header, default=[],
144
+ metavar="'Name: value'",
145
+ help="extra request header, repeatable (never saved to the history)")
146
+ watch.set_defaults(handler=cmd_watch)
147
+
148
+ for name, handler, help_text in (
149
+ ("report", cmd_report, "latency percentiles from history"),
150
+ ("diagnose", cmd_diagnose, "explain what looks wrong"),
151
+ ):
152
+ sub = commands.add_parser(name, help=help_text)
153
+ add_common(sub)
154
+ sub.add_argument("--limit", type=_positive_int, default=DEFAULT_HISTORY_LIMIT)
155
+ sub.set_defaults(handler=handler)
156
+ return parser
157
+
158
+
159
+ def main(argv: list[str] | None = None) -> int:
160
+ args = build_parser().parse_args(argv)
161
+ if not _is_http_url(args.url):
162
+ print(f"expected an http(s) URL, got {args.url!r}", file=sys.stderr)
163
+ return EXIT_BAD_INPUT
164
+ return args.handler(args)
165
+
166
+
167
+ if __name__ == "__main__":
168
+ sys.exit(main(sys.argv[1:]))
@@ -0,0 +1,122 @@
1
+ """apipulse diagnose: rule-based reading of probe history.
2
+
3
+ Turns raw timings into plain-language findings, such as which phase of the
4
+ request got slower. This is the layer an LLM could later explain or extend.
5
+ """
6
+
7
+ import statistics
8
+ from dataclasses import dataclass
9
+ from typing import Sequence
10
+
11
+ from .monitor import CLIENT_ERROR_STATUS, SERVER_ERROR_STATUS, percentile
12
+ from .store import ProbeRecord
13
+
14
+ MIN_RECORDS_FOR_TREND = 6
15
+ SLOWDOWN_FACTOR = 2.0 # recent median this many times the baseline median
16
+ MIN_SLOWDOWN_MS = 20.0 # ignore "doubling" of tiny numbers
17
+ SPREAD_FACTOR = 3.0 # p95 this many times p50 means inconsistent latency
18
+ MIN_SPREAD_MS = 20.0
19
+ CRITICAL_FAILURE_RATE = 0.5
20
+
21
+ PHASES = {
22
+ "dns_ms": "DNS lookup",
23
+ "connect_ms": "TCP connect (network path or a full accept queue)",
24
+ "tls_ms": "TLS handshake",
25
+ "ttfb_ms": "server processing time (the API itself is slow)",
26
+ }
27
+
28
+ SEVERITY_RANK = {"info": 0, "warning": 1, "critical": 2}
29
+
30
+
31
+ @dataclass(frozen=True)
32
+ class Finding:
33
+ severity: str # "info" | "warning" | "critical"
34
+ message: str
35
+
36
+
37
+ def worst_severity(findings: Sequence[Finding]) -> str:
38
+ return max((f.severity for f in findings), key=SEVERITY_RANK.__getitem__, default="info")
39
+
40
+
41
+ def _availability(records: Sequence[ProbeRecord]) -> tuple[Finding, ...]:
42
+ failures = [r for r in records if r.is_failure]
43
+ if not failures:
44
+ return ()
45
+ rate = len(failures) / len(records)
46
+ latest_error = next((r.error for r in reversed(failures) if r.error), None)
47
+ latest_status = next((r.status_code for r in reversed(failures) if r.error is None), None)
48
+ detail = latest_error or (f"latest status {latest_status}" if latest_status else "")
49
+ severity = "critical" if rate >= CRITICAL_FAILURE_RATE else "warning"
50
+ message = f"{len(failures)} of {len(records)} probes failed ({rate:.0%})"
51
+ return (Finding(severity, f"{message}; {detail}" if detail else message),)
52
+
53
+
54
+ def _client_errors(records: Sequence[ProbeRecord]) -> tuple[Finding, ...]:
55
+ # 4xx is not an outage, but it usually means the probe itself is misconfigured
56
+ rejected = [
57
+ r for r in records
58
+ if r.status_code is not None and CLIENT_ERROR_STATUS <= r.status_code < SERVER_ERROR_STATUS
59
+ ]
60
+ if not rejected:
61
+ return ()
62
+ return (
63
+ Finding(
64
+ "warning",
65
+ f"{len(rejected)} of {len(records)} probes got a 4xx response "
66
+ f"(latest {rejected[-1].status_code}); check the URL or credentials",
67
+ ),
68
+ )
69
+
70
+
71
+ def _spread(timed: Sequence[ProbeRecord]) -> tuple[Finding, ...]:
72
+ if len(timed) < 2:
73
+ return ()
74
+ latencies = sorted(r.total_ms for r in timed)
75
+ p50, p95 = percentile(latencies, 0.50), percentile(latencies, 0.95)
76
+ if p95 > SPREAD_FACTOR * p50 and p95 - p50 > MIN_SPREAD_MS:
77
+ return (Finding("warning", f"Latency is inconsistent: p50 {p50:.0f} ms but p95 {p95:.0f} ms"),)
78
+ return ()
79
+
80
+
81
+ def _median(records: Sequence[ProbeRecord], phase: str) -> float:
82
+ return statistics.median(getattr(r, phase) for r in records)
83
+
84
+
85
+ def _slowdown(timed: Sequence[ProbeRecord]) -> tuple[Finding, ...]:
86
+ if len(timed) < MIN_RECORDS_FOR_TREND:
87
+ return ()
88
+ half = len(timed) // 2
89
+ baseline, recent = timed[:half], timed[half:]
90
+ before, after = _median(baseline, "total_ms"), _median(recent, "total_ms")
91
+ if after < SLOWDOWN_FACTOR * before or after - before < MIN_SLOWDOWN_MS:
92
+ return ()
93
+
94
+ growth = {phase: _median(recent, phase) - _median(baseline, phase) for phase in PHASES}
95
+ culprit = max(growth, key=growth.__getitem__)
96
+ return (
97
+ Finding(
98
+ "warning",
99
+ f"Slowed down: median latency rose from {before:.0f} ms to {after:.0f} ms. "
100
+ f"Biggest increase: {PHASES[culprit]} (+{growth[culprit]:.0f} ms)",
101
+ ),
102
+ )
103
+
104
+
105
+ def diagnose(records: Sequence[ProbeRecord]) -> tuple[Finding, ...]:
106
+ """Findings for records ordered oldest first; a single 'info' finding means healthy."""
107
+ if not records:
108
+ return (Finding("info", "No data yet: run `watch` first"),)
109
+
110
+ timed = [r for r in records if r.error is None and r.total_ms is not None]
111
+ findings = _availability(records) + _client_errors(records) + _spread(timed) + _slowdown(timed)
112
+ if findings:
113
+ return findings
114
+
115
+ latencies = sorted(r.total_ms for r in timed)
116
+ return (
117
+ Finding(
118
+ "info",
119
+ f"Healthy: p50 {percentile(latencies, 0.50):.1f} ms, "
120
+ f"p95 {percentile(latencies, 0.95):.1f} ms over {len(timed)} probes",
121
+ ),
122
+ )