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.
@@ -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
+ [![CI](https://github.com/rt87/fastapi-perfstats/actions/workflows/ci.yml/badge.svg)](https://github.com/rt87/fastapi-perfstats/actions/workflows/ci.yml)
51
+ ![Python](https://img.shields.io/badge/python-3.12--3.15-blue)
52
+ ![License](https://img.shields.io/github/license/rt87/fastapi-perfstats)
53
+ ![Ruff](https://img.shields.io/badge/lint-ruff-261230)
54
+ ![mypy](https://img.shields.io/badge/checked%20with-mypy%20strict-2a6db2)
55
+ ![Status](https://img.shields.io/badge/status-alpha-yellow)
56
+ [![PyPI](https://img.shields.io/pypi/v/fastapi-perfstats)](https://pypi.org/project/fastapi-perfstats/)
57
+ ![AI-assisted](https://img.shields.io/badge/AI--assisted-Claude%20Code-8A2BE2)
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,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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.