fastapi-perfstats 0.1.0__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.
- fastapi_perfstats/__init__.py +73 -0
- fastapi_perfstats/auth.py +60 -0
- fastapi_perfstats/collector.py +159 -0
- fastapi_perfstats/config.py +163 -0
- fastapi_perfstats/ext/__init__.py +9 -0
- fastapi_perfstats/ext/base.py +102 -0
- fastapi_perfstats/ext/recent.py +167 -0
- fastapi_perfstats/ext/sizes.py +109 -0
- fastapi_perfstats/ext/stddev.py +84 -0
- fastapi_perfstats/headers.py +36 -0
- fastapi_perfstats/keys.py +34 -0
- fastapi_perfstats/lifecycle.py +43 -0
- fastapi_perfstats/live.py +133 -0
- fastapi_perfstats/middleware.py +81 -0
- fastapi_perfstats/models.py +93 -0
- fastapi_perfstats/mounts.py +34 -0
- fastapi_perfstats/page.py +299 -0
- fastapi_perfstats/parts.py +9 -0
- fastapi_perfstats/prometheus.py +96 -0
- fastapi_perfstats/py.typed +0 -0
- fastapi_perfstats/reset.py +60 -0
- fastapi_perfstats/route.py +48 -0
- fastapi_perfstats/slow_context.py +118 -0
- fastapi_perfstats/sqlite_schema.py +53 -0
- fastapi_perfstats/stores.py +400 -0
- fastapi_perfstats-0.1.0.dist-info/METADATA +478 -0
- fastapi_perfstats-0.1.0.dist-info/RECORD +29 -0
- fastapi_perfstats-0.1.0.dist-info/WHEEL +4 -0
- fastapi_perfstats-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,478 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fastapi-perfstats
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Tiny per-route call statistics, slow-call log and stats page for Starlette/FastAPI apps
|
|
5
|
+
Project-URL: Homepage, https://github.com/rt87/fastapi-perfstats
|
|
6
|
+
Project-URL: Repository, https://github.com/rt87/fastapi-perfstats
|
|
7
|
+
Project-URL: Issues, https://github.com/rt87/fastapi-perfstats/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/rt87/fastapi-perfstats/blob/main/CHANGELOG.md
|
|
9
|
+
Author-email: rt87 <rt87@users.noreply.github.com>
|
|
10
|
+
License: MIT License
|
|
11
|
+
|
|
12
|
+
Copyright (c) 2026 rt87
|
|
13
|
+
|
|
14
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
15
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
16
|
+
in the Software without restriction, including without limitation the rights
|
|
17
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
18
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
19
|
+
furnished to do so, subject to the following conditions:
|
|
20
|
+
|
|
21
|
+
The above copyright notice and this permission notice shall be included in all
|
|
22
|
+
copies or substantial portions of the Software.
|
|
23
|
+
|
|
24
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
25
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
26
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
27
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
28
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
29
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
30
|
+
SOFTWARE.
|
|
31
|
+
License-File: LICENSE
|
|
32
|
+
Keywords: asgi,fastapi,latency,metrics,middleware,slow-calls,starlette,statistics
|
|
33
|
+
Classifier: Development Status :: 3 - Alpha
|
|
34
|
+
Classifier: Framework :: AsyncIO
|
|
35
|
+
Classifier: Framework :: FastAPI
|
|
36
|
+
Classifier: Intended Audience :: Developers
|
|
37
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
38
|
+
Classifier: Programming Language :: Python :: 3
|
|
39
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
40
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
41
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
42
|
+
Classifier: Programming Language :: Python :: 3.15
|
|
43
|
+
Classifier: Typing :: Typed
|
|
44
|
+
Requires-Python: >=3.12
|
|
45
|
+
Requires-Dist: starlette>=0.37
|
|
46
|
+
Description-Content-Type: text/markdown
|
|
47
|
+
|
|
48
|
+
# fastapi-perfstats
|
|
49
|
+
|
|
50
|
+
[](https://github.com/rt87/fastapi-perfstats/actions/workflows/ci.yml)
|
|
51
|
+

|
|
52
|
+

|
|
53
|
+

|
|
54
|
+

|
|
55
|
+

|
|
56
|
+
[](https://pypi.org/project/fastapi-perfstats/)
|
|
57
|
+

|
|
58
|
+
|
|
59
|
+
Tiny per-route call statistics for Starlette / FastAPI, in the spirit of `pg_stat_statements`: call counts,
|
|
60
|
+
errors, latency quantiles, a bounded slow-call log and a built-in HTML stats page.
|
|
61
|
+
|
|
62
|
+
## Contents
|
|
63
|
+
|
|
64
|
+
- [Features](#features) - [Install](#install) - [Quick start](#quick-start) - [The stats page](#the-stats-page)
|
|
65
|
+
- [Configuration](#configuration) - [pg_stat-like behaviour](#pg_stat-like-behaviour)
|
|
66
|
+
- [Limits and caveats](#limits-and-caveats) - [Demo](#demo)
|
|
67
|
+
|
|
68
|
+
## Features
|
|
69
|
+
|
|
70
|
+
- Pure ASGI middleware (no `BaseHTTPMiddleware`), or a route class / decorator for single routes.
|
|
71
|
+
- Key = `METHOD` + route template (`GET /items/{item_id}` is one key); raw path only for unmatched requests.
|
|
72
|
+
- Per key: count, 5xx and 4xx counts, min / mean / max and configurable quantiles (default p50, p95, p99).
|
|
73
|
+
- Storage: in-memory (default) or SQLite (stdlib), both size-bounded, behind one small ABC.
|
|
74
|
+
- Slow-call log with a configurable threshold.
|
|
75
|
+
- HTML page (sortable, filterable, dark/light, no external assets) plus JSON, optional HTTP Basic auth.
|
|
76
|
+
- Runtime dependency: `starlette` only; works on Starlette and FastAPI apps.
|
|
77
|
+
|
|
78
|
+
## Install
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
pip install fastapi-perfstats
|
|
82
|
+
# or
|
|
83
|
+
uv add fastapi-perfstats
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
The latest development version: `pip install "git+https://github.com/rt87/fastapi-perfstats"`.
|
|
87
|
+
|
|
88
|
+
Python 3.12-3.15. The only dependency is `starlette`; `fastapi-perfstats` never depends on `fastapi`. Middleware,
|
|
89
|
+
the stats page and `mount_stats` work on plain Starlette apps; only `StatsRoute` / `collector.route_class` and
|
|
90
|
+
`dependencies=[Depends(...)]` need FastAPI installed (clear `ImportError` otherwise).
|
|
91
|
+
|
|
92
|
+
## Quick start
|
|
93
|
+
|
|
94
|
+
App level (all routes):
|
|
95
|
+
|
|
96
|
+
```python
|
|
97
|
+
from fastapi import FastAPI
|
|
98
|
+
from fastapi_perfstats import StatsCollector, StatsConfig, mount_stats
|
|
99
|
+
|
|
100
|
+
collector = StatsCollector(StatsConfig(basic_auth=("admin", "change-me")))
|
|
101
|
+
app = FastAPI()
|
|
102
|
+
app.add_middleware(collector.middleware)
|
|
103
|
+
mount_stats(app, collector) # page at /stats, JSON at /stats.json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
Route level (one router, or a single function):
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
from fastapi import APIRouter
|
|
110
|
+
|
|
111
|
+
from fastapi_perfstats import StatsRoute
|
|
112
|
+
|
|
113
|
+
router = APIRouter(route_class=StatsRoute) # records into the process-wide default collector
|
|
114
|
+
router = APIRouter(route_class=collector.route_class) # or: bound to your own collector (and its config)
|
|
115
|
+
|
|
116
|
+
|
|
117
|
+
@app.get("/one")
|
|
118
|
+
@collector.track("one") # a single async endpoint
|
|
119
|
+
async def one(): ...
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`StatsRoute` uses a default collector (plain `StatsConfig()` unless you call `set_default_collector(my_collector)`
|
|
123
|
+
first); pass that same collector to `mount_stats` to see its data. Do not combine middleware and route class / decorator for the same routes (they would count twice).
|
|
124
|
+
|
|
125
|
+
## The stats page
|
|
126
|
+
|
|
127
|
+
Served at `stats_path` (default `/stats`), JSON at `/stats.json`. Three plain tables, each starting with separate `Method` and `Route` columns (the JSON has `method` and `route`
|
|
128
|
+
fields next to the combined `key`): call frequency per route
|
|
129
|
+
(count, 5xx, 4xx, share, calls per minute), longest runtimes per route (max, quantiles, mean, min) and the slow-call
|
|
130
|
+
list (time, route, duration, status). Click a header to sort, type in the filter box to narrow rows. Colours follow
|
|
131
|
+
`prefers-color-scheme`. The small script is inline, there are no CDN or framework requests, and every string
|
|
132
|
+
(route keys come from request data) is HTML-escaped.
|
|
133
|
+
|
|
134
|
+
**The page exposes your API structure and timings: do not leave it public.** Set `basic_auth=("user", "pw")`
|
|
135
|
+
(or `BasicAuth(...)`); it covers HTML and JSON, compares with `secrets.compare_digest` and answers 401 with
|
|
136
|
+
`WWW-Authenticate`. Mounting without auth logs a warning. `dependencies=[Depends(...)]` on `mount_stats` /
|
|
137
|
+
`stats_router` can be used in addition. Basic auth is only sensible over HTTPS or on localhost.
|
|
138
|
+
|
|
139
|
+
## Configuration
|
|
140
|
+
|
|
141
|
+
All options live in the frozen dataclass `StatsConfig`.
|
|
142
|
+
|
|
143
|
+
| Option | Default | Meaning |
|
|
144
|
+
| --- | --- | --- |
|
|
145
|
+
| `quantiles` | `(0.5, 0.95, 0.99)` | Replaces the defaults when given; values in (0, 1] |
|
|
146
|
+
| `storage` | `"memory"` | `"memory"`, `"sqlite"` or a custom `StatsStore` instance |
|
|
147
|
+
| `sqlite_path` | `"fastapi_perfstats.db"` | SQLite file |
|
|
148
|
+
| `window_size` | `1000` | Last N durations kept per route (quantile window) |
|
|
149
|
+
| `max_routes` | `200` | Distinct keys; further keys go to the `other` bucket |
|
|
150
|
+
| `slow_threshold_ms` | `500.0` | Calls at or above are logged individually; `None` disables |
|
|
151
|
+
| `max_slow_calls` | `200` | Slow-log size, oldest dropped first |
|
|
152
|
+
| `stats_path` | `"/stats"` | Page URL |
|
|
153
|
+
| `exclude_paths` | `("/health",)` | Never counted (the stats paths always are excluded) |
|
|
154
|
+
| `key_func` | `None` | `scope -> key` (or `None` to skip the call) |
|
|
155
|
+
| `max_key_length` | `200` | Longer keys are truncated |
|
|
156
|
+
| `basic_auth` | `None` | `(user, password)` or `BasicAuth` |
|
|
157
|
+
| `unmatched` | `"group"` | How unmatched requests are keyed: `group`, `raw` or `skip` |
|
|
158
|
+
| `close_on_shutdown` | `True` | Close the store on app shutdown |
|
|
159
|
+
| `access` | `None` | Extra access check `request -> bool` for the stats endpoints |
|
|
160
|
+
| `allow_reset` | `False` | Enable the reset endpoint |
|
|
161
|
+
| `slow_thresholds` | `{}` | Per-key slow thresholds in ms |
|
|
162
|
+
| `slow_capture_query` | `False` | Store the redacted query string with slow calls |
|
|
163
|
+
| `redact_query_params` | see source | Query parameter name fragments that are redacted |
|
|
164
|
+
| `slow_request_id_headers` | `("x-request-id", "traceparent")` | Headers tried for a request id |
|
|
165
|
+
| `slow_context` | `None` | Hook adding context to slow calls |
|
|
166
|
+
| `track_sizes` | `True` | Track request/response payload sizes |
|
|
167
|
+
| `recent_minutes` | `60` | Minutes of recent activity kept (0..1440, 0 = off) |
|
|
168
|
+
| `recent_windows` | `(1, 5, 15)` | Recent windows in minutes |
|
|
169
|
+
| `refresh_seconds` | `None` | Initial value of the page's auto-refresh selector (`None`/0 = Off, 5, 15, 60) |
|
|
170
|
+
| `prometheus` | `False` | Enable the Prometheus text endpoint |
|
|
171
|
+
| `prometheus_prefix` | `"fastapi_perfstats"` | Prometheus metric name prefix |
|
|
172
|
+
|
|
173
|
+
## pg_stat-like behaviour
|
|
174
|
+
|
|
175
|
+
- Counts, errors, min, max and mean are all-time aggregates per key; quantiles come from the last `window_size`
|
|
176
|
+
durations, computed on read with the nearest-rank method.
|
|
177
|
+
- Only calls with duration >= `slow_threshold_ms` enter the slow log (timestamp, key, duration, status); it is a
|
|
178
|
+
bounded list that keeps the most recent `max_slow_calls` entries.
|
|
179
|
+
- SQLite: `record()` only enqueues; one writer thread applies batches in a single transaction, so the event loop
|
|
180
|
+
never waits for disk. If the queue (10 000) is full, records are dropped (`dropped` counter) rather than blocking.
|
|
181
|
+
Rows are pruned to `window_size` per route and `max_slow_calls`.
|
|
182
|
+
|
|
183
|
+
## Feature details
|
|
184
|
+
|
|
185
|
+
### Storage
|
|
186
|
+
|
|
187
|
+
Both stores (`MemoryStore`, `SqliteStore`) take an optional `extensions` sequence (`None` = `fastapi_perfstats.ext.EXTENSIONS`)
|
|
188
|
+
and call each extension's hooks with the final key (also for the `other` bucket).
|
|
189
|
+
|
|
190
|
+
- **Slow calls** keep `query`, `request_id` and `context` (memory: on `SlowCall`; SQLite: table `slow_call_extra`, context
|
|
191
|
+
as JSON, pruned together with the slow log). The threshold comes from `config.slow_threshold_for(key)`.
|
|
192
|
+
- **`reset()`** clears all statistics and every extension's state. The SQLite store applies it in order with the writer
|
|
193
|
+
queue: records enqueued before the call are gone, later ones are kept. On a closed store it raises `RuntimeError`.
|
|
194
|
+
- **`dropped`** counts records the SQLite queue could not take; **`close()`** may be called more than once.
|
|
195
|
+
- If an extension hook or SQL statement fails inside the SQLite writer, that batch is rolled back and logged; the
|
|
196
|
+
writer keeps running.
|
|
197
|
+
|
|
198
|
+
### SQLite schema
|
|
199
|
+
|
|
200
|
+
A new or empty database file gets the core tables (`routes`, `durations`, `slow_calls`) and is stamped with
|
|
201
|
+
`PRAGMA user_version = 1`. Opening a stamped file of the same version changes nothing. A file with another version, or
|
|
202
|
+
with tables but no stamp, is refused with a `RuntimeError` naming the file and both versions; nothing is migrated or
|
|
203
|
+
deleted, so delete the file or point `sqlite_path` elsewhere. Concurrent workers are serialised with `BEGIN IMMEDIATE`.
|
|
204
|
+
Extension tables are created idempotently by their owners and are not part of the version check.
|
|
205
|
+
|
|
206
|
+
### Mounted sub-applications
|
|
207
|
+
|
|
208
|
+
Routes under `Mount(...)` are keyed with the full mount prefix, e.g. `GET /v1/items/{item_id}` and
|
|
209
|
+
`GET /v2/items/{item_id}` stay separate; nested mounts give the whole prefix. A proxy root path (`--root-path`) never
|
|
210
|
+
appears in keys, and FastAPI `include_router(prefix=...)` is not prefixed twice. A mounted ASGI app without inner
|
|
211
|
+
routing (`app.mount("/static", ...)`) is keyed by the mount path (`GET /static`). The suite runs in CI against the
|
|
212
|
+
lowest allowed Starlette (0.37), so the declared floor is tested.
|
|
213
|
+
|
|
214
|
+
Limit: a mount path with parameters (`Mount("/tenants/{tenant}", ...)`) contributes the raw value (one key per
|
|
215
|
+
tenant), because the scope only carries the matched path, not the mount template. Avoid parameters in mount paths, or
|
|
216
|
+
set `key_func`.
|
|
217
|
+
|
|
218
|
+
### Unmatched requests
|
|
219
|
+
|
|
220
|
+
Requests that match no route (404s from scanners, `/.env`, ...) must not use up the `max_routes` slots, so
|
|
221
|
+
`StatsConfig.unmatched` decides how they are keyed:
|
|
222
|
+
|
|
223
|
+
- `"group"` (default): one key per method, `GET <unmatched>`, whatever the path.
|
|
224
|
+
- `"raw"`: the raw path becomes the key (unbounded until `max_routes` is reached, then `other`).
|
|
225
|
+
- `"skip"`: nothing is recorded.
|
|
226
|
+
|
|
227
|
+
HTTP methods outside the standard set are keyed as `OTHER` (`PROPFIND /items/1` becomes `OTHER /items/{item_id}`).
|
|
228
|
+
A method mismatch on an existing route (405) keeps its route template. A custom `key_func` bypasses all of this.
|
|
229
|
+
|
|
230
|
+
### Timing semantics
|
|
231
|
+
|
|
232
|
+
`StatsMiddleware` stops the clock when the last body chunk is handed to the server, so Starlette background tasks
|
|
233
|
+
that run afterwards are not counted, while a streaming response is measured including its pauses between chunks.
|
|
234
|
+
(`StatsRoute` and `track()` measure until the handler returns; body streaming is excluded there.)
|
|
235
|
+
|
|
236
|
+
- A client disconnect before the response completed is recorded as status `499` (counts as a 4xx error).
|
|
237
|
+
- An exception after the response started but before it completed is recorded as `500`.
|
|
238
|
+
- Disconnect messages arriving after completion change nothing.
|
|
239
|
+
- With `track_sizes`, request and response body bytes are summed from the ASGI messages.
|
|
240
|
+
|
|
241
|
+
### Lifecycle
|
|
242
|
+
|
|
243
|
+
`StatsMiddleware` handles the ASGI lifespan: when the app reports `lifespan.shutdown.complete` or
|
|
244
|
+
`lifespan.shutdown.failed`, the store is closed first (in a worker thread, as it may wait up to 10 s for the SQLite
|
|
245
|
+
writer), so queued records are persisted. Set `close_on_shutdown=False` to leave the store open. `close()` may be
|
|
246
|
+
called more than once.
|
|
247
|
+
|
|
248
|
+
If you only use `StatsRoute` or `track()` (no middleware), close the collector yourself:
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
@asynccontextmanager
|
|
252
|
+
async def lifespan(app):
|
|
253
|
+
yield
|
|
254
|
+
collector.close()
|
|
255
|
+
|
|
256
|
+
|
|
257
|
+
app = FastAPI(lifespan=lifespan)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Records the SQLite writer queue could not take are counted: the JSON has `"dropped"` and the page shows
|
|
261
|
+
`N records dropped (writer queue full)` when it is above 0.
|
|
262
|
+
|
|
263
|
+
### Security headers
|
|
264
|
+
|
|
265
|
+
The HTML page is CSP-compatible without extra files: its inline `<style>` and `<script>` are allowed by SHA-256
|
|
266
|
+
hashes computed from the exact served text, so it also works under a strict global policy. It is sent with
|
|
267
|
+
`Content-Security-Policy: default-src 'none'; style-src <hash>; script-src <hash>; img-src 'self' data:; connect-src
|
|
268
|
+
'self'; base-uri 'none'; form-action 'self'; frame-ancestors 'none'`, `X-Content-Type-Options: nosniff`,
|
|
269
|
+
`Referrer-Policy: no-referrer`, `X-Frame-Options: DENY` and `Cache-Control: no-store`. JSON and the 401/403 responses
|
|
270
|
+
carry `Cache-Control: no-store` and `X-Content-Type-Options: nosniff`. The page uses no inline event handlers, no
|
|
271
|
+
`style="..."` attributes and no dynamic content inside `<script>` / `<style>`; data is passed via `data-*` attributes.
|
|
272
|
+
|
|
273
|
+
### Access control
|
|
274
|
+
|
|
275
|
+
Every stats endpoint (page, JSON and the optional reset / metrics endpoints) runs the same check: HTTP Basic first
|
|
276
|
+
(`basic_auth`, 401 on failure), then `access`, a callable `request -> bool` that may be sync or async. `False` gives
|
|
277
|
+
`403 Forbidden`; an exception in the check propagates (500) and is never swallowed. The check is not called when Basic
|
|
278
|
+
auth already failed. No "mounted WITHOUT authentication" warning is logged when `access` is set.
|
|
279
|
+
|
|
280
|
+
```python
|
|
281
|
+
from fastapi_perfstats import StatsConfig, localhost_only
|
|
282
|
+
|
|
283
|
+
|
|
284
|
+
async def staff_only(request) -> bool:
|
|
285
|
+
return await my_session_store.is_staff(request.cookies.get("session"))
|
|
286
|
+
|
|
287
|
+
|
|
288
|
+
StatsConfig(access=staff_only) # any sync or async check
|
|
289
|
+
StatsConfig(access=localhost_only) # loopback clients only (127.0.0.1, ::1)
|
|
290
|
+
```
|
|
291
|
+
|
|
292
|
+
`localhost_only` is unreliable behind a reverse proxy, where every client appears as the proxy's address.
|
|
293
|
+
|
|
294
|
+
### Reset
|
|
295
|
+
|
|
296
|
+
`collector.reset()` clears all statistics (routes, durations, slow log, extension state) without a restart; with SQLite
|
|
297
|
+
the reset is applied in order with the writer queue, so records recorded before the call are deleted and later ones
|
|
298
|
+
are kept. A custom store without `reset()` raises `NotImplementedError`.
|
|
299
|
+
|
|
300
|
+
With `allow_reset=True` (default `False`) the stats router also serves `POST {stats_path}/reset` and the page shows a
|
|
301
|
+
"Reset statistics" button (confirm dialog, then reload). The endpoint uses the same authorization as the page and
|
|
302
|
+
additionally needs the header `X-Stats-Reset: 1`: browsers send Basic credentials automatically, but an HTML form cannot
|
|
303
|
+
set a custom header and a cross-origin `fetch` with it needs a CORS preflight, which is never allowed.
|
|
304
|
+
|
|
305
|
+
| Result | Meaning |
|
|
306
|
+
| --- | --- |
|
|
307
|
+
| 204 (`Cache-Control: no-store`) | statistics cleared |
|
|
308
|
+
| 400 | header `X-Stats-Reset: 1` missing |
|
|
309
|
+
| 401 / 403 | authorization failed |
|
|
310
|
+
| 405 | not a POST (or `allow_reset` is off: no such route) |
|
|
311
|
+
| 501 | the store does not support reset |
|
|
312
|
+
|
|
313
|
+
The button posts to the page's own URL plus `/reset` (taken from `location.pathname` in the browser), so it is right
|
|
314
|
+
for any `path`, mount prefix or proxy root path. The reset path lies below `stats_path`, so it is never recorded.
|
|
315
|
+
|
|
316
|
+
```bash
|
|
317
|
+
curl -X POST -H "X-Stats-Reset: 1" -u admin:secret http://localhost:8000/stats/reset
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
### Error rates and stddev
|
|
321
|
+
|
|
322
|
+
Each route shows `5xx %` and `4xx %` (errors divided by all calls of that route) and `Stddev`, the population
|
|
323
|
+
standard deviation of its durations in ms (`sqrt(E[x^2] - mean^2)`, computed from a running sum of squares over all
|
|
324
|
+
calls, not just the quantile window). A route with a single call has a stddev of `0.0`. The JSON has
|
|
325
|
+
`error_rate_4xx`, `error_rate_5xx` and `stddev_ms` per route. With SQLite the sums live in the table `ext_stddev`;
|
|
326
|
+
memory and SQLite give identical numbers.
|
|
327
|
+
|
|
328
|
+
### Per-route slow thresholds
|
|
329
|
+
|
|
330
|
+
`slow_thresholds` overrides `slow_threshold_ms` per route, for example when a report export legitimately takes
|
|
331
|
+
seconds and a lookup should take milliseconds:
|
|
332
|
+
|
|
333
|
+
```python
|
|
334
|
+
StatsConfig(
|
|
335
|
+
slow_threshold_ms=500,
|
|
336
|
+
slow_thresholds={
|
|
337
|
+
"GET /reports/{report_id}": 3000, # full key: this method and route only
|
|
338
|
+
"/lookup/{item_id}": 20, # route template: any method
|
|
339
|
+
"/internal/export": None, # None: never logged as slow
|
|
340
|
+
},
|
|
341
|
+
)
|
|
342
|
+
```
|
|
343
|
+
|
|
344
|
+
The lookup order is the exact key, then the route template without the method, then the global threshold. Only plain
|
|
345
|
+
dict lookups are used (no patterns or globs). A global `slow_threshold_ms=None` still logs routes that have their own
|
|
346
|
+
value. Values must be `None` or `>= 0`, keys must not be empty. The slow-call heading shows the number of overrides
|
|
347
|
+
(`Slow calls (>= 500 ms, 2 route overrides)`) and the JSON has `slow_thresholds`.
|
|
348
|
+
|
|
349
|
+
### Slow-call context
|
|
350
|
+
|
|
351
|
+
A slow-call entry can carry a request or trace id, the query string and custom context. The extras are computed only
|
|
352
|
+
for calls that are actually slow, so fast calls cost nothing extra.
|
|
353
|
+
|
|
354
|
+
- **Request id** (on by default): the first header from `slow_request_id_headers` (default `x-request-id`,
|
|
355
|
+
`traceparent`) that is present. For `traceparent` only the 32-hex trace id is kept; invalid values are ignored. Values
|
|
356
|
+
are cut to 128 characters.
|
|
357
|
+
- **Query string** (`slow_capture_query=True`, off by default): stored with the values of parameters whose NAME contains
|
|
358
|
+
one of `redact_query_params` (case-insensitive substring, default `pass`, `tok`, `secret`, `key`, `auth`, `sig`,
|
|
359
|
+
`session`, `code`) replaced by `[redacted]`; at most 500 characters.
|
|
360
|
+
- **Context hook** (`slow_context`): a function `scope -> {name: value}` for your own correlation data. At most 10
|
|
361
|
+
items, keys and values cut to 200 characters. If it raises, the request is unaffected: the error is logged once per
|
|
362
|
+
exception type on the `fastapi_perfstats` logger and `{"context_error": "<ExceptionTypeName>"}` is stored.
|
|
363
|
+
|
|
364
|
+
Privacy: the defaults store no query and no custom context. Request and response bodies and all headers other than the
|
|
365
|
+
configured id headers are never read or stored. The page and the JSON show `Request id`, `Query` and `Context`; the
|
|
366
|
+
page escapes all of them.
|
|
367
|
+
|
|
368
|
+
### Payload sizes
|
|
369
|
+
|
|
370
|
+
With `track_sizes=True` (default) the middleware sums the request body bytes and the response body bytes of every call
|
|
371
|
+
(streamed bodies across all chunks). The page gets a "Payload sizes" table (`Mean request`, `Mean response`,
|
|
372
|
+
`Max response`, in `B`/`KiB`/`MiB` with the raw byte count used for sorting) and the JSON route entries gain
|
|
373
|
+
`mean_request_bytes`, `mean_response_bytes` and `max_response_bytes`.
|
|
374
|
+
|
|
375
|
+
- Only calls with both sizes known contribute; `StatsRoute`, `track()` and `track_sizes=False` leave them unknown, shown
|
|
376
|
+
as `n/a` (`None` in JSON).
|
|
377
|
+
- Sizes are body bytes before/after any compression by an outer layer, without headers. The body of a `HEAD` response
|
|
378
|
+
is not counted (servers do not send it).
|
|
379
|
+
- SQLite keeps the aggregates in its own table `ext_sizes` (one row per route).
|
|
380
|
+
|
|
381
|
+
### Recent activity
|
|
382
|
+
|
|
383
|
+
Everything else is all-time; the recent columns show what happens now, like a load average. Calls are counted in
|
|
384
|
+
one-minute buckets (wall clock, `int(ts // 60)`); `recent_minutes` (default 60, max 1440, `0` turns the feature off)
|
|
385
|
+
buckets are kept per route, and `recent_windows` (default `(1, 5, 15)`) picks the windows. The frequency table adds
|
|
386
|
+
`Calls/min (Nm)` per window and `5xx % (Nm)` for the largest window; the plain `Calls/min` is then labelled
|
|
387
|
+
`Calls/min (all)`. The JSON has `recent` (`"1m"`, `"5m"`, ... with `calls`, `calls_per_min`, `errors_5xx`,
|
|
388
|
+
`error_rate_5xx`, `mean_ms`) and `series` (per-minute counts, oldest first, zero-filled, `recent_minutes` long) per
|
|
389
|
+
route. A window covers the current, partial minute plus the previous `N - 1`; for a route younger than the window the
|
|
390
|
+
rate is divided by its age. A timestamp that goes backwards (clock change) is counted in the newest bucket. SQLite keeps
|
|
391
|
+
the buckets in the table `ext_recent`, pruned on every write batch; with several worker processes the counts add up.
|
|
392
|
+
Recent quantiles are not offered (they would need histograms).
|
|
393
|
+
|
|
394
|
+
### Live page
|
|
395
|
+
|
|
396
|
+
The page has an auto-refresh selector (Off / 5 s / 15 s / 60 s); `refresh_seconds` (`0`, `5`, `15` or `60`) sets its
|
|
397
|
+
initial value, `None` (default) and `0` start it Off. The choice is remembered in the browser
|
|
398
|
+
(`localStorage`). A refresh fetches the page again and swaps the table bodies, so sort order and filter text are kept;
|
|
399
|
+
if the fetch fails a "refresh failed" note appears and the old data stays.
|
|
400
|
+
|
|
401
|
+
With `recent_minutes > 0` the frequency table gets a `Last N min` column: an inline SVG sparkline of calls per minute
|
|
402
|
+
(oldest to newest) per route, no external assets.
|
|
403
|
+
|
|
404
|
+
### Prometheus
|
|
405
|
+
|
|
406
|
+
Set `prometheus=True` to serve the statistics in the Prometheus text format at `{stats_path}/metrics` (protected like
|
|
407
|
+
the other stats endpoints, not recorded itself). Metric names start with `prometheus_prefix` (default `fastapi_perfstats`):
|
|
408
|
+
`_requests_total`, `_responses_errors_total{status_class}`, `_request_duration_seconds` (summary) and `_dropped_records_total`
|
|
409
|
+
(always exposed, 0 until the store drops something). All families keep their HELP/TYPE lines even before the first
|
|
410
|
+
request. Labels are `method` and `route`.
|
|
411
|
+
|
|
412
|
+
```yaml
|
|
413
|
+
scrape_configs:
|
|
414
|
+
- job_name: my-api
|
|
415
|
+
metrics_path: /stats/metrics
|
|
416
|
+
basic_auth: {username: admin, password_file: /etc/prometheus/stats-password}
|
|
417
|
+
static_configs:
|
|
418
|
+
- targets: ["api.example.internal:8000"]
|
|
419
|
+
```
|
|
420
|
+
|
|
421
|
+
Quantiles cover the last `window_size` calls per route and cannot be aggregated across instances. For fleet-wide SLOs
|
|
422
|
+
use prometheus-fastapi-instrumentator or prometheus-client histograms.
|
|
423
|
+
|
|
424
|
+
### Overhead
|
|
425
|
+
|
|
426
|
+
`benchmarks/overhead.py` drives ASGI apps in-process (no HTTP client, no network) and reports the median per-request
|
|
427
|
+
time, with and without fastapi-perfstats. The table shows the added cost per request, measured by the `Benchmark`
|
|
428
|
+
workflow on a GitHub-hosted Linux runner with Python 3.14.4 (`uv run python benchmarks/overhead.py --n 20000
|
|
429
|
+
--repeats 7`); the numbers are indicative only and vary between runs. The `trivial` endpoint returns a tiny JSON
|
|
430
|
+
body, the `realistic` one builds and serialises a JSON payload of about 6 kB and does a fixed amount of CPU work.
|
|
431
|
+
|
|
432
|
+
| Scenario | Added, trivial endpoint (µs) | Added, realistic endpoint (µs) |
|
|
433
|
+
| --- | ---: | ---: |
|
|
434
|
+
| Starlette + middleware (memory) | +16.6 | +24.8 |
|
|
435
|
+
| Starlette + middleware (sqlite) | +12.9 | +21.3 |
|
|
436
|
+
| FastAPI + middleware | +21.0 | +25.6 |
|
|
437
|
+
| FastAPI + `route_class` | +29.7 | +32.1 |
|
|
438
|
+
|
|
439
|
+
The added cost is roughly constant per request (about 13 to 32 µs here), so the relative overhead is
|
|
440
|
+
`added µs / endpoint duration`:
|
|
441
|
+
|
|
442
|
+
| Endpoint duration | Overhead |
|
|
443
|
+
| ---: | ---: |
|
|
444
|
+
| 1 ms | ≈ 1.3-3.2 % |
|
|
445
|
+
| 10 ms | ≈ 0.13-0.32 % |
|
|
446
|
+
| 100 ms | ≈ 0.013-0.032 % |
|
|
447
|
+
|
|
448
|
+
fastapi-perfstats exists to find slow endpoints, and for those the overhead is negligible.
|
|
449
|
+
|
|
450
|
+
## Limits and caveats
|
|
451
|
+
|
|
452
|
+
- Statistics are per process; there is no merging across workers. With SQLite, several processes write into the
|
|
453
|
+
same file (WAL, atomic upserts, counts add up); in-memory shows only the own process.
|
|
454
|
+
- Alpha: the API may change; not load-tested. SQLite stats can lose the last few records on a hard crash.
|
|
455
|
+
- Exclusion (`exclude_paths`, and the stats paths themselves) compares the raw request path. A stats router mounted
|
|
456
|
+
below a `Mount` prefix is therefore only excluded if the prefixed path (e.g. `/api/admin/stats`) is added to
|
|
457
|
+
`exclude_paths`; otherwise the stats requests themselves are counted.
|
|
458
|
+
- Unmatched paths (404s) share one `<unmatched>` key per method by default (`unmatched`); `max_routes` still caps the
|
|
459
|
+
number of distinct keys, the rest go to `other`.
|
|
460
|
+
|
|
461
|
+
## Development
|
|
462
|
+
|
|
463
|
+
```bash
|
|
464
|
+
uv sync
|
|
465
|
+
uv run pytest # tests + coverage
|
|
466
|
+
uv run ruff check .
|
|
467
|
+
uv run ruff format --check .
|
|
468
|
+
uv run mypy # strict; tests/demo only relax the "must be annotated" rules
|
|
469
|
+
```
|
|
470
|
+
|
|
471
|
+
The package ships `py.typed`.
|
|
472
|
+
|
|
473
|
+
## Demo
|
|
474
|
+
|
|
475
|
+
```bash
|
|
476
|
+
uv sync
|
|
477
|
+
uv run python examples/demo.py # then open http://127.0.0.1:8000/items/1 and /stats (admin / change-me)
|
|
478
|
+
```
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
fastapi_perfstats/__init__.py,sha256=wshXvGRWYij0QH5LoihETCjTIcMxPgkQG2Hh2X1GqRM,2120
|
|
2
|
+
fastapi_perfstats/auth.py,sha256=D0ul6KexMs_BxaM-VUFMJHQI_CIg-hWIZhn5V2l-XKI,2175
|
|
3
|
+
fastapi_perfstats/collector.py,sha256=aTPIBGWrENPD-H8MPDN90LIVuYa8d1KdkaNPyRr2NT8,6228
|
|
4
|
+
fastapi_perfstats/config.py,sha256=m6UnxR84sC521wIH3aqYvZ7g4lD-84rm768dgreEhtc,8636
|
|
5
|
+
fastapi_perfstats/headers.py,sha256=EbyA86QZuFy5dRUqzpCGw-N6nebwhJMXGUCXd6saS1g,1395
|
|
6
|
+
fastapi_perfstats/keys.py,sha256=n3tAnB8-KwSn0TxxNGaM5rz14BszRSf9WtIKa5e8uHY,1381
|
|
7
|
+
fastapi_perfstats/lifecycle.py,sha256=vvpNdvxBTF0JySrnY50qU_2r6OlD4JUO0qGhiYnVH8c,1466
|
|
8
|
+
fastapi_perfstats/live.py,sha256=vq1Y6u7qoEQ5cdV_dCWiiwR6nyftUse2_ymbzz5v-tQ,4845
|
|
9
|
+
fastapi_perfstats/middleware.py,sha256=cbR8HgzMq3h-alSvJgFlQYCyWI5XXPfu0-ZPvzFE2t4,3338
|
|
10
|
+
fastapi_perfstats/models.py,sha256=ANb-sbT2ugBsqIOgqWRXaDbTtgeiEyJDyfkSIeigg50,2540
|
|
11
|
+
fastapi_perfstats/mounts.py,sha256=dN0U1H5zWXB6Sj2-5LcLoPRXGE1dQg36npeG5LBumuc,1467
|
|
12
|
+
fastapi_perfstats/page.py,sha256=oGpsq78p8UzUfxMB_hJ0m_qtZIRrm2f2HXm4Md3Ol9Y,12723
|
|
13
|
+
fastapi_perfstats/parts.py,sha256=RAab_9mrb0Rl_42vw1KQ2n-_IzOoBnVYFN-cUlbDbyI,384
|
|
14
|
+
fastapi_perfstats/prometheus.py,sha256=TH-AcSJEvrjRWjijx5GK7Wh_l1Q_84soQhgLzudDaig,3941
|
|
15
|
+
fastapi_perfstats/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
16
|
+
fastapi_perfstats/reset.py,sha256=uiqY2oTqQ0WX5UdHm7BYp7ynBp_e8HvWJcf-09A4Hxk,2485
|
|
17
|
+
fastapi_perfstats/route.py,sha256=HEDd1TkZKwz4eA49eMkHYBqYpLNcU6XpiJWcxkNaSvo,1738
|
|
18
|
+
fastapi_perfstats/slow_context.py,sha256=8hcpoZiPdx8tuhUE-UyI3PBuJsFkGTdA4CDOJ4CIOw8,4258
|
|
19
|
+
fastapi_perfstats/sqlite_schema.py,sha256=LbTVfwWTD-StBhcJvnerGs7FSUjcrVy5TN_nvGYP_AI,2154
|
|
20
|
+
fastapi_perfstats/stores.py,sha256=l7ZIC6Eoq6Co3bgPJIX7u3wiDyhbvzVOos0JOra06Zw,15481
|
|
21
|
+
fastapi_perfstats/ext/__init__.py,sha256=V8mSxHl9qCHXhjtJzsDhhTFwgo5pJJx1IykswR53aNw,349
|
|
22
|
+
fastapi_perfstats/ext/base.py,sha256=gZ7eUBCA4GGwLxDzbSPgbkFTFdccGbdJ11DgZn8b3pc,3587
|
|
23
|
+
fastapi_perfstats/ext/recent.py,sha256=ftAmgWYDhUtmYzECejGniYmrzVEeVhIGCl0Ab_cVzK0,7151
|
|
24
|
+
fastapi_perfstats/ext/sizes.py,sha256=8FAXLyeO-D_onRIh8BkuoIvz3LgQo80imXFdNcMGEOc,4229
|
|
25
|
+
fastapi_perfstats/ext/stddev.py,sha256=VhOvbJejLXfptrxWcNvx69VkpdlKH7-sn1MEx40Mbbk,3140
|
|
26
|
+
fastapi_perfstats-0.1.0.dist-info/METADATA,sha256=2M9nHhbeAwJIgNS-g8UvRR4QuoRFwdalQ_VQ5fI8kJs,25897
|
|
27
|
+
fastapi_perfstats-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
|
|
28
|
+
fastapi_perfstats-0.1.0.dist-info/licenses/LICENSE,sha256=xcnBTJtNei4rinLqzvU86FWsK0SmGUygpW1S99iHnfg,1061
|
|
29
|
+
fastapi_perfstats-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 rt87
|
|
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.
|