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 +21 -0
- apipulse-0.1.1/PKG-INFO +153 -0
- apipulse-0.1.1/README.md +133 -0
- apipulse-0.1.1/apipulse/__init__.py +3 -0
- apipulse-0.1.1/apipulse/__main__.py +5 -0
- apipulse-0.1.1/apipulse/cli.py +168 -0
- apipulse-0.1.1/apipulse/diagnose.py +122 -0
- apipulse-0.1.1/apipulse/monitor.py +102 -0
- apipulse-0.1.1/apipulse/probe.py +166 -0
- apipulse-0.1.1/apipulse/store.py +95 -0
- apipulse-0.1.1/apipulse.egg-info/PKG-INFO +153 -0
- apipulse-0.1.1/apipulse.egg-info/SOURCES.txt +20 -0
- apipulse-0.1.1/apipulse.egg-info/dependency_links.txt +1 -0
- apipulse-0.1.1/apipulse.egg-info/entry_points.txt +2 -0
- apipulse-0.1.1/apipulse.egg-info/top_level.txt +1 -0
- apipulse-0.1.1/pyproject.toml +36 -0
- apipulse-0.1.1/setup.cfg +4 -0
- apipulse-0.1.1/tests/test_apipulse.py +157 -0
- apipulse-0.1.1/tests/test_diagnose.py +105 -0
- apipulse-0.1.1/tests/test_monitor.py +64 -0
- apipulse-0.1.1/tests/test_probe.py +120 -0
- apipulse-0.1.1/tests/test_store.py +54 -0
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.
|
apipulse-0.1.1/PKG-INFO
ADDED
|
@@ -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
|
+
[](https://github.com/Athina09/apipulse/actions/workflows/tests.yml)
|
|
24
|
+
[](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
|
+

|
|
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
|
+

|
|
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)
|
apipulse-0.1.1/README.md
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
# apipulse
|
|
2
|
+
|
|
3
|
+
[](https://github.com/Athina09/apipulse/actions/workflows/tests.yml)
|
|
4
|
+
[](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
|
+

|
|
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
|
+

|
|
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,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
|
+
)
|