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,81 @@
1
+ """Pure ASGI middleware measuring every HTTP request."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import time
6
+ from typing import TYPE_CHECKING
7
+
8
+ from starlette.types import ASGIApp, Message, Receive, Scope, Send
9
+
10
+ from fastapi_perfstats import lifecycle
11
+ from fastapi_perfstats.models import CLIENT_CLOSED_STATUS
12
+
13
+ if TYPE_CHECKING:
14
+ from fastapi_perfstats.collector import StatsCollector
15
+
16
+
17
+ class StatsMiddleware:
18
+ """Pure ASGI middleware (no BaseHTTPMiddleware: no body buffering, no task-per-request overhead)."""
19
+
20
+ def __init__(self, app: ASGIApp, collector: StatsCollector) -> None:
21
+ self.app = app
22
+ self.collector = collector
23
+
24
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
25
+ if scope["type"] == "lifespan":
26
+ await lifecycle.handle_lifespan(self.collector, self.app, scope, receive, send)
27
+ return
28
+ if scope["type"] != "http" or self.collector.is_excluded(scope.get("path", "")):
29
+ await self.app(scope, receive, send)
30
+ return
31
+ status = 500 # stays 500 if the app raises before sending a response
32
+ started = False
33
+ completed = False # the final body chunk was handed to the server
34
+ disconnected = False
35
+ end = 0.0
36
+ track_sizes = self.collector.config.track_sizes
37
+ count_body = scope.get("method") != "HEAD" # servers drop the body of a HEAD response: it is not sent
38
+ request_bytes = 0
39
+ response_bytes = 0
40
+
41
+ async def receive_wrapper() -> Message:
42
+ nonlocal disconnected, request_bytes
43
+ message = await receive()
44
+ if message["type"] == "http.disconnect":
45
+ if not completed:
46
+ disconnected = True
47
+ elif track_sizes and message["type"] == "http.request":
48
+ request_bytes += len(message.get("body", b""))
49
+ return message
50
+
51
+ async def send_wrapper(message: Message) -> None:
52
+ nonlocal status, started, completed, end, response_bytes
53
+ if message["type"] == "http.response.start":
54
+ status = message["status"]
55
+ started = True
56
+ elif message["type"] == "http.response.body":
57
+ if track_sizes and count_body:
58
+ response_bytes += len(message.get("body", b""))
59
+ if not completed and not message.get("more_body", False):
60
+ end = time.perf_counter()
61
+ completed = True
62
+ await send(message)
63
+
64
+ start = time.perf_counter()
65
+ failed = True
66
+ try:
67
+ await self.app(scope, receive_wrapper, send_wrapper)
68
+ failed = False
69
+ finally:
70
+ elapsed = ((end if completed else time.perf_counter()) - start) * 1000
71
+ if disconnected and not completed:
72
+ status = CLIENT_CLOSED_STATUS
73
+ elif failed and not completed:
74
+ status = 500 # never started, or the stream broke after the status line went out
75
+ self.collector.finish(
76
+ scope,
77
+ elapsed,
78
+ status,
79
+ request_bytes=request_bytes if track_sizes else None,
80
+ response_bytes=response_bytes if track_sizes else None,
81
+ ) # after the call: scope["route"] is filled in by now
@@ -0,0 +1,93 @@
1
+ """Plain result types and the percentile helper."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import math
6
+ from collections.abc import Mapping
7
+ from dataclasses import dataclass, field
8
+
9
+ OTHER_KEY = "other"
10
+ UNMATCHED_ROUTE = "<unmatched>"
11
+ OTHER_METHOD = "OTHER"
12
+ KNOWN_METHODS = frozenset({"GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE", "CONNECT"})
13
+ CLIENT_CLOSED_STATUS = 499
14
+
15
+
16
+ def nearest_rank(sorted_values: list[float], q: float) -> float:
17
+ """Nearest-rank percentile: the smallest value with at least ``q`` of the data at or below it."""
18
+ if not sorted_values:
19
+ return 0.0
20
+ rank = max(1, math.ceil(q * len(sorted_values)))
21
+ return sorted_values[min(rank, len(sorted_values)) - 1]
22
+
23
+
24
+ @dataclass(frozen=True, slots=True)
25
+ class CallRecord:
26
+ """One finished call, as handed to ``StatsStore.record`` and to extensions."""
27
+
28
+ key: str
29
+ duration_ms: float
30
+ status: int
31
+ ts: float # time.time() when the call finished
32
+ method: str = ""
33
+ path: str = "" # raw path, never used as a key
34
+ request_bytes: int | None = None
35
+ response_bytes: int | None = None
36
+ query: str | None = None
37
+ request_id: str | None = None
38
+ context: Mapping[str, str] | None = None
39
+
40
+
41
+ @dataclass(frozen=True, slots=True)
42
+ class SlowExtra:
43
+ """Optional extra detail stored with a slow call."""
44
+
45
+ query: str | None = None
46
+ request_id: str | None = None
47
+ context: Mapping[str, str] | None = None
48
+
49
+
50
+ @dataclass
51
+ class RecentStats:
52
+ """Aggregates over one recent window (see ``StatsConfig.recent_windows``)."""
53
+
54
+ calls: int
55
+ calls_per_min: float
56
+ errors_5xx: int
57
+ error_rate_5xx: float
58
+ mean_ms: float
59
+
60
+
61
+ @dataclass
62
+ class RouteStats:
63
+ key: str
64
+ count: int
65
+ errors_4xx: int
66
+ errors_5xx: int
67
+ min_ms: float
68
+ mean_ms: float
69
+ max_ms: float
70
+ quantiles: dict[str, float] = field(default_factory=dict)
71
+ first_ts: float = 0.0
72
+ last_ts: float = 0.0
73
+ share: float = 0.0
74
+ rate_per_min: float = 0.0
75
+ error_rate_4xx: float = 0.0
76
+ error_rate_5xx: float = 0.0
77
+ stddev_ms: float | None = None
78
+ mean_request_bytes: float | None = None
79
+ mean_response_bytes: float | None = None
80
+ max_response_bytes: int | None = None
81
+ recent: dict[str, RecentStats] = field(default_factory=dict)
82
+ series: list[int] = field(default_factory=list)
83
+
84
+
85
+ @dataclass
86
+ class SlowCall:
87
+ ts: float
88
+ key: str
89
+ duration_ms: float
90
+ status: int
91
+ query: str | None = None
92
+ request_id: str | None = None
93
+ context: dict[str, str] = field(default_factory=dict)
@@ -0,0 +1,34 @@
1
+ """Mounted sub-application support (owned by #4)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping
6
+ from typing import Any
7
+
8
+ from starlette.routing import Mount
9
+
10
+
11
+ def mount_prefix(scope: Mapping[str, Any]) -> str:
12
+ """Path prefix added by ``Mount()``s: ``root_path`` minus the app's own root path, ``""`` when not mounted.
13
+
14
+ Starlette's ``Mount.matches`` (checked on 0.37 and 1.x) puts the root path seen *before* the first mount into
15
+ ``scope["app_root_path"]`` once and extends ``scope["root_path"]`` by each matched mount path. A proxy root path
16
+ (``--root-path``) is part of both and therefore cancels out.
17
+
18
+ When no inner route matched (``app.mount("/static", asgi_app)``), ``scope["route"]`` is the ``Mount`` itself and
19
+ its path is already the key template, so its own part is not repeated in the prefix.
20
+
21
+ Limitation: a mount path with parameters (``/tenants/{tenant}``) contributes the raw value, as the scope only
22
+ carries the matched path, not the mount template.
23
+ """
24
+ if "app_root_path" not in scope:
25
+ return ""
26
+ root_path = str(scope.get("root_path", ""))
27
+ app_root_path = str(scope["app_root_path"])
28
+ if not root_path.startswith(app_root_path):
29
+ return ""
30
+ prefix = root_path[len(app_root_path) :]
31
+ route = scope.get("route")
32
+ if isinstance(route, Mount) and route.path and prefix.endswith(route.path):
33
+ prefix = prefix[: -len(route.path)]
34
+ return prefix
@@ -0,0 +1,299 @@
1
+ """HTML + JSON stats page. WARNING: route keys come from request data; every string is escaped."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ from collections.abc import Awaitable, Callable, Sequence
7
+ from dataclasses import asdict, dataclass
8
+ from datetime import UTC, datetime
9
+ from html import escape
10
+ from typing import Any
11
+
12
+ from starlette.concurrency import run_in_threadpool
13
+ from starlette.requests import Request
14
+ from starlette.responses import HTMLResponse, JSONResponse, Response
15
+ from starlette.routing import Route, Router
16
+
17
+ from fastapi_perfstats import auth, ext, headers, parts
18
+ from fastapi_perfstats.collector import StatsCollector
19
+ from fastapi_perfstats.config import StatsConfig, quantile_label
20
+ from fastapi_perfstats.ext.base import Column, EndpointSpec
21
+ from fastapi_perfstats.models import RouteStats, SlowCall
22
+
23
+ log = logging.getLogger("fastapi_perfstats")
24
+
25
+ _CSS = """
26
+ :root{--bg:#fff;--fg:#1b1f24;--mut:#667;--line:#d0d7de;--head:#f3f5f7;--bad:#b3261e}
27
+ @media (prefers-color-scheme:dark){
28
+ :root{--bg:#14171a;--fg:#e6e9ec;--mut:#98a2ad;--line:#2f353b;--head:#1d2227;--bad:#ff8a80}}
29
+ body{background:var(--bg);color:var(--fg);font:14px/1.4 system-ui,sans-serif;margin:1rem 2rem}
30
+ table{border-collapse:collapse;width:100%;margin:.5rem 0 1.5rem}
31
+ th,td{border:1px solid var(--line);padding:.3rem .6rem;text-align:right}
32
+ th:nth-child(-n+2),td:nth-child(-n+2){text-align:left}
33
+ th{background:var(--head);cursor:pointer;user-select:none}
34
+ .bad{color:var(--bad)} input{background:var(--bg);color:var(--fg);border:1px solid var(--line);padding:.2rem}
35
+ h1,h2{font-weight:600} .mut{color:var(--mut)}
36
+ """
37
+
38
+ _JS = """
39
+ document.querySelectorAll('table.s').forEach(function(t){
40
+ var tb=t.tBodies[0], dir=1;
41
+ t.tHead.querySelectorAll('th').forEach(function(th,i){
42
+ th.addEventListener('click',function(){
43
+ dir=-dir;
44
+ Array.from(tb.rows).sort(function(a,b){
45
+ var x=a.cells[i],y=b.cells[i],p=x.dataset.v,q=y.dataset.v;
46
+ if(p!==undefined&&q!==undefined)return (parseFloat(p)-parseFloat(q))*dir;
47
+ return x.textContent.localeCompare(y.textContent)*dir;
48
+ }).forEach(function(r){tb.appendChild(r);});
49
+ });
50
+ });
51
+ });
52
+ document.querySelectorAll('input.f').forEach(function(inp){
53
+ inp.addEventListener('input',function(){
54
+ var t=document.getElementById(inp.dataset.t),s=inp.value.toLowerCase();
55
+ Array.from(t.tBodies[0].rows).forEach(function(r){
56
+ r.style.display=r.textContent.toLowerCase().indexOf(s)<0?'none':'';
57
+ });
58
+ });
59
+ });
60
+ """
61
+
62
+
63
+ def split_key(key: str) -> tuple[str, str]:
64
+ """``"GET /items/{id}"`` -> ``("GET", "/items/{id}")``; keys without a leading method -> ``("", key)``."""
65
+ method, sep, route = key.partition(" ")
66
+ if sep and method.isalpha() and method.isupper():
67
+ return method, route
68
+ return "", key
69
+
70
+
71
+ def _num(v: float, digits: int = 2) -> str:
72
+ return f"{v:.{digits}f}"
73
+
74
+
75
+ def _td(text: object, value: float | None = None, cls: str = "", raw: bool = False) -> str:
76
+ v = "" if value is None else f' data-v="{value!r}"'
77
+ c = f' class="{cls}"' if cls else ""
78
+ return f"<td{v}{c}>{text if raw else escape(str(text))}</td>"
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class _CoreColumn(Column):
83
+ """A core column; ``cls`` yields the CSS class of its cell (extension columns have none)."""
84
+
85
+ cls: Callable[[Any], str] = lambda item: ""
86
+
87
+
88
+ def _method(item: RouteStats | SlowCall, config: StatsConfig) -> tuple[str, float | None]:
89
+ return split_key(item.key)[0], None
90
+
91
+
92
+ def _route(item: RouteStats | SlowCall, config: StatsConfig) -> tuple[str, float | None]:
93
+ return split_key(item.key)[1], None
94
+
95
+
96
+ def _key_columns(table: Any) -> list[Column]:
97
+ return [Column(table, "Method", 10, _method), Column(table, "Route", 20, _route)]
98
+
99
+
100
+ def _quantile_cell(label: str) -> Callable[[Any, StatsConfig], tuple[str, float | None]]:
101
+ return lambda r, config: (_num(r.quantiles[label]), r.quantiles[label])
102
+
103
+
104
+ def core_columns(config: StatsConfig) -> list[Column]:
105
+ """The built-in columns of every table (extensions add theirs through ``Extension.columns``)."""
106
+ rate_header = "Calls/min (all)" if config.recent_minutes > 0 else "Calls/min"
107
+ cols: list[Column] = [
108
+ *_key_columns("freq"),
109
+ Column("freq", "Count", 30, lambda r, c: (str(r.count), r.count)),
110
+ _CoreColumn(
111
+ "freq",
112
+ "5xx",
113
+ 40,
114
+ lambda r, c: (str(r.errors_5xx), r.errors_5xx),
115
+ cls=lambda r: "bad" if r.errors_5xx else "",
116
+ ),
117
+ Column("freq", "4xx", 60, lambda r, c: (str(r.errors_4xx), r.errors_4xx)),
118
+ Column("freq", "Share", 80, lambda r, c: (f"{r.share * 100:.1f}%", r.share)),
119
+ Column("freq", rate_header, 90, lambda r, c: (_num(r.rate_per_min), r.rate_per_min)),
120
+ *_key_columns("rt"),
121
+ Column("rt", "Max", 30, lambda r, c: (_num(r.max_ms), r.max_ms)),
122
+ Column("rt", "Mean", 60, lambda r, c: (_num(r.mean_ms), r.mean_ms)),
123
+ Column("rt", "Min", 70, lambda r, c: (_num(r.min_ms), r.min_ms)),
124
+ *_key_columns("slow"),
125
+ Column("slow", "Time", 30, lambda s, c: (_ts(s.ts), s.ts)),
126
+ Column("slow", "Duration", 40, lambda s, c: (_num(s.duration_ms), s.duration_ms)),
127
+ _CoreColumn(
128
+ "slow", "Status", 50, lambda s, c: (str(s.status), s.status), cls=lambda s: "bad" if s.status >= 500 else ""
129
+ ),
130
+ *_key_columns("sizes"),
131
+ ]
132
+ cols += [
133
+ Column("rt", quantile_label(q), 40 + i, _quantile_cell(quantile_label(q)))
134
+ for i, q in enumerate(config.quantiles)
135
+ ]
136
+ return cols
137
+
138
+
139
+ def _columns_for(table: str, config: StatsConfig) -> list[Column]:
140
+ cols = [c for c in core_columns(config) if c.table == table]
141
+ for extension in ext.EXTENSIONS:
142
+ cols += [c for c in extension.columns(config) if c.table == table]
143
+ return sorted(cols, key=lambda c: c.order)
144
+
145
+
146
+ def _table(table_id: str, columns: Sequence[Column], items: Sequence[Any], config: StatsConfig) -> str:
147
+ head = "".join(f"<th>{escape(c.header)}</th>" for c in columns)
148
+ rows = []
149
+ for item in items:
150
+ cells = []
151
+ for c in columns:
152
+ text, value = c.cell(item, config)
153
+ cls = c.cls(item) if isinstance(c, _CoreColumn) else ""
154
+ cells.append(_td(text, value, cls, c.raw_html))
155
+ rows.append("<tr>" + "".join(cells) + "</tr>")
156
+ return (
157
+ f'<input class="f" data-t="{table_id}" placeholder="filter..." aria-label="filter {table_id}">'
158
+ f'<table class="s" id="{table_id}"><thead><tr>{head}</tr></thead><tbody>{"".join(rows)}</tbody></table>'
159
+ )
160
+
161
+
162
+ def _ts(ts: float) -> str:
163
+ return datetime.fromtimestamp(ts, UTC).strftime("%Y-%m-%d %H:%M:%S UTC")
164
+
165
+
166
+ def style_text() -> str:
167
+ """The inline stylesheet of the page."""
168
+ return _CSS
169
+
170
+
171
+ def script_text(collector: StatsCollector) -> str:
172
+ """The inline script of the page: the core script followed by the script of every page part, in order."""
173
+ return _JS + "".join(part.js for part in parts.PAGE_PARTS)
174
+
175
+
176
+ def _body_attrs(config: StatsConfig) -> str:
177
+ merged: dict[str, str] = {}
178
+ for part in parts.PAGE_PARTS:
179
+ merged.update(part.body_attrs(config))
180
+ return "".join(f' {escape(k)}="{escape(v)}"' for k, v in merged.items())
181
+
182
+
183
+ def render_html(collector: StatsCollector) -> str:
184
+ cfg = collector.config
185
+ routes = collector.store.routes()
186
+ slow = collector.store.slow_calls()
187
+ by_max = sorted(routes, key=lambda r: r.max_ms, reverse=True)
188
+ sizes_columns = _columns_for("sizes", cfg)
189
+ sizes_table = ""
190
+ if len(sizes_columns) > 2: # more than Method + Route: some extension contributes columns
191
+ sizes_table = "<h2>Payload sizes</h2>" + _table("sizes", sizes_columns, routes, cfg)
192
+ tops = "".join(part.html_top(collector) for part in parts.PAGE_PARTS)
193
+ return (
194
+ '<!doctype html><html lang="en"><head><meta charset="utf-8">'
195
+ '<meta name="viewport" content="width=device-width,initial-scale=1"><title>API stats</title>'
196
+ f"<style>{style_text()}</style></head><body{_body_attrs(cfg)}><h1>API stats</h1>"
197
+ '<p class="mut">Click a header to sort, type to filter. Durations in ms. '
198
+ f"Quantiles over the last {cfg.window_size} calls per route. "
199
+ f'<a href="{escape(cfg.stats_path)}.json">JSON</a></p>'
200
+ + tops
201
+ + "<h2>Call frequency</h2>"
202
+ + _table("freq", _columns_for("freq", cfg), routes, cfg)
203
+ + "<h2>Longest runtimes</h2>"
204
+ + _table("rt", _columns_for("rt", cfg), by_max, cfg)
205
+ + f"<h2>Slow calls ({escape(cfg.slow_threshold_summary())})</h2>"
206
+ + _table("slow", _columns_for("slow", cfg), slow, cfg)
207
+ + sizes_table
208
+ + f"<script>{script_text(collector)}</script></body></html>"
209
+ )
210
+
211
+
212
+ def _with_parts(d: dict[str, Any]) -> dict[str, Any]:
213
+ d["method"], d["route"] = split_key(d["key"]) # "key" (METHOD + template) stays for compatibility
214
+ return d
215
+
216
+
217
+ def render_json(collector: StatsCollector) -> dict[str, Any]:
218
+ cfg = collector.config
219
+ return {
220
+ "quantiles": [quantile_label(q) for q in cfg.quantiles],
221
+ "slow_threshold_ms": cfg.slow_threshold_ms,
222
+ "routes": [_with_parts(asdict(r)) for r in collector.store.routes()],
223
+ "slow_calls": [_with_parts(asdict(s)) for s in collector.store.slow_calls()],
224
+ "dropped": collector.store.dropped,
225
+ "slow_thresholds": dict(cfg.slow_thresholds),
226
+ }
227
+
228
+
229
+ def stats_router(collector: StatsCollector, path: str | None = None, dependencies: Sequence[Any] | None = None) -> Any:
230
+ """Build a router serving the page at ``path`` and JSON at ``path + ".json"``.
231
+
232
+ Without ``dependencies`` this is a plain Starlette ``Router`` (no fastapi import). With FastAPI
233
+ ``dependencies`` (e.g. ``[Depends(require_admin)]``) a FastAPI ``APIRouter`` is built instead (imports fastapi
234
+ only then). Basic auth from the config applies in both cases. The page exposes your route structure and
235
+ timings: do NOT leave it public.
236
+ """
237
+ config = collector.config
238
+ p = (path or config.stats_path).rstrip("/") or "/"
239
+ if config.credentials is None and config.access is None and not dependencies:
240
+ log.warning("fastapi-perfstats: stats page at %s is mounted WITHOUT authentication", p)
241
+
242
+ async def denied(request: Request) -> Response | None:
243
+ response = await auth.authorize(request, config)
244
+ if response is not None:
245
+ response.headers.update(headers.data_headers())
246
+ return response
247
+
248
+ async def stats_page(request: Request) -> Response:
249
+ if (response := await denied(request)) is not None:
250
+ return response
251
+ html = await run_in_threadpool(render_html, collector)
252
+ return HTMLResponse(html, headers=headers.page_headers(style_text(), script_text(collector)))
253
+
254
+ async def stats_json(request: Request) -> Response:
255
+ if (response := await denied(request)) is not None:
256
+ return response
257
+ return JSONResponse(await run_in_threadpool(render_json, collector), headers=headers.data_headers())
258
+
259
+ def endpoint_for(spec: EndpointSpec) -> Callable[[Request], Awaitable[Response]]:
260
+ inner = spec.handler(collector)
261
+
262
+ async def endpoint(request: Request) -> Response:
263
+ if (response := await denied(request)) is not None:
264
+ return response
265
+ response = await inner(request)
266
+ response.headers.update(headers.data_headers())
267
+ return response
268
+
269
+ return endpoint
270
+
271
+ extra = [
272
+ (p + spec.suffix, endpoint_for(spec), list(spec.methods)) for spec in parts.ENDPOINTS if spec.enabled(config)
273
+ ]
274
+
275
+ if dependencies:
276
+ try:
277
+ from fastapi import APIRouter
278
+ except ImportError as exc:
279
+ raise ImportError("stats_router(dependencies=...) needs FastAPI installed") from exc
280
+ router = APIRouter(dependencies=list(dependencies), include_in_schema=False)
281
+ router.add_api_route(p, stats_page, methods=["GET"], response_class=HTMLResponse)
282
+ router.add_api_route(p + ".json", stats_json, methods=["GET"])
283
+ for route_path, endpoint, methods in extra:
284
+ router.add_api_route(route_path, endpoint, methods=methods)
285
+ return router
286
+ return Router(
287
+ routes=[
288
+ Route(p, stats_page, methods=["GET"]),
289
+ Route(p + ".json", stats_json, methods=["GET"]),
290
+ *[Route(route_path, endpoint, methods=methods) for route_path, endpoint, methods in extra],
291
+ ]
292
+ )
293
+
294
+
295
+ def mount_stats(
296
+ app: Any, collector: StatsCollector, path: str | None = None, dependencies: Sequence[Any] | None = None
297
+ ) -> None:
298
+ """Add the stats routes to a Starlette or FastAPI ``app``."""
299
+ app.router.routes.extend(stats_router(collector, path, dependencies).routes)
@@ -0,0 +1,9 @@
1
+ """Registries of page parts and extra endpoints, in fixed order."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from fastapi_perfstats import lifecycle, live, prometheus, reset
6
+ from fastapi_perfstats.ext.base import EndpointSpec, PagePart
7
+
8
+ PAGE_PARTS: tuple[PagePart, ...] = (lifecycle.PART, reset.PART, live.PART)
9
+ ENDPOINTS: tuple[EndpointSpec, ...] = (reset.ENDPOINT, prometheus.ENDPOINT)
@@ -0,0 +1,96 @@
1
+ """Prometheus text export (owned by #17)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Awaitable, Callable
6
+ from typing import TYPE_CHECKING
7
+
8
+ from starlette.requests import Request
9
+ from starlette.responses import Response
10
+
11
+ from fastapi_perfstats.config import quantile_label
12
+ from fastapi_perfstats.ext.base import EndpointSpec
13
+
14
+ if TYPE_CHECKING:
15
+ from fastapi_perfstats.collector import StatsCollector
16
+
17
+
18
+ CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
19
+
20
+
21
+ def _escape_label(value: str) -> str:
22
+ return value.replace("\\", "\\\\").replace('"', '\\"').replace("\n", "\\n")
23
+
24
+
25
+ def _escape_help(value: str) -> str:
26
+ return value.replace("\\", "\\\\").replace("\n", "\\n")
27
+
28
+
29
+ def _family(name: str, kind: str, help_text: str, samples: list[str]) -> list[str]:
30
+ """HELP/TYPE header plus samples; a family without samples keeps its header lines."""
31
+ return [f"# HELP {name} {_escape_help(help_text)}", f"# TYPE {name} {kind}", *samples]
32
+
33
+
34
+ def _number(value: float) -> str:
35
+ return repr(float(value)) if not float(value).is_integer() else str(int(value))
36
+
37
+
38
+ def render_prometheus(collector: StatsCollector) -> str:
39
+ """Prometheus text exposition (format 0.0.4) of the collector's per-route statistics.
40
+
41
+ Quantiles come from the sliding window (last ``window_size`` calls per route) and are not aggregatable across
42
+ instances. Every family is always exposed; the dropped-records counter is 0 until the store drops something.
43
+ """
44
+ from fastapi_perfstats.page import split_key # lazy: page imports parts, which imports this module
45
+
46
+ config = collector.config
47
+ prefix = config.prometheus_prefix
48
+ labels: dict[str, str] = {}
49
+ routes = sorted(collector.store.routes(), key=lambda r: r.key)
50
+ for r in routes:
51
+ method, route = split_key(r.key)
52
+ labels[r.key] = f'method="{_escape_label(method)}",route="{_escape_label(route)}"'
53
+ requests = [f"{prefix}_requests_total{{{labels[r.key]}}} {r.count}" for r in routes]
54
+ errors: list[str] = []
55
+ summary: list[str] = []
56
+ for r in routes:
57
+ errors.append(f'{prefix}_responses_errors_total{{{labels[r.key]},status_class="4xx"}} {r.errors_4xx}')
58
+ errors.append(f'{prefix}_responses_errors_total{{{labels[r.key]},status_class="5xx"}} {r.errors_5xx}')
59
+ for q in config.quantiles:
60
+ ms = r.quantiles.get(quantile_label(q))
61
+ if ms is not None:
62
+ summary.append(
63
+ f'{prefix}_request_duration_seconds{{{labels[r.key]},quantile="{q:g}"}} {_number(ms / 1000)}'
64
+ )
65
+ summary.append(
66
+ f"{prefix}_request_duration_seconds_sum{{{labels[r.key]}}} {_number(r.mean_ms * r.count / 1000)}"
67
+ )
68
+ summary.append(f"{prefix}_request_duration_seconds_count{{{labels[r.key]}}} {r.count}")
69
+ dropped = collector.store.dropped
70
+ lines = [
71
+ *_family(f"{prefix}_requests_total", "counter", "Requests handled per route.", requests),
72
+ *_family(f"{prefix}_responses_errors_total", "counter", "Error responses per route and class.", errors),
73
+ *_family(
74
+ f"{prefix}_request_duration_seconds",
75
+ "summary",
76
+ "Request duration in seconds; quantiles over the last window_size calls per route.",
77
+ summary,
78
+ ),
79
+ *_family(
80
+ f"{prefix}_dropped_records_total",
81
+ "counter",
82
+ "Records dropped because the store could not keep up.",
83
+ [f"{prefix}_dropped_records_total {dropped}"],
84
+ ),
85
+ ]
86
+ return "\n".join(lines) + "\n" if lines else ""
87
+
88
+
89
+ def _handler(collector: StatsCollector) -> Callable[[Request], Awaitable[Response]]:
90
+ async def metrics(request: Request) -> Response:
91
+ return Response(render_prometheus(collector), media_type=CONTENT_TYPE)
92
+
93
+ return metrics
94
+
95
+
96
+ ENDPOINT = EndpointSpec(suffix="/metrics", methods=("GET",), enabled=lambda config: config.prometheus, handler=_handler)
File without changes
@@ -0,0 +1,60 @@
1
+ """Reset endpoint and page button (owned by #10).
2
+
3
+ ``POST {stats_path}/reset`` clears all statistics. Browsers attach Basic credentials on their own, so a request must
4
+ also carry the header ``X-Stats-Reset: 1``: an HTML form cannot set it and a cross-origin ``fetch`` with it needs a
5
+ CORS preflight, which this library never allows. Authorization itself is applied by the stats router.
6
+
7
+ The button posts to ``location.pathname + "/reset"``: the page URL already contains every mount prefix and proxy root
8
+ path, so it is right wherever the router is mounted.
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from collections.abc import Awaitable, Callable
14
+ from typing import TYPE_CHECKING
15
+
16
+ from starlette.concurrency import run_in_threadpool
17
+ from starlette.requests import Request
18
+ from starlette.responses import PlainTextResponse, Response
19
+
20
+ from fastapi_perfstats.ext.base import EndpointSpec, PagePart
21
+
22
+ if TYPE_CHECKING:
23
+ from fastapi_perfstats.collector import StatsCollector
24
+
25
+ SUFFIX = "/reset"
26
+ HEADER = "x-stats-reset"
27
+ BUTTON_ID = "stats-reset"
28
+
29
+ _JS = (
30
+ "\n(function(){var b=document.getElementById('stats-reset');if(!b){return;}"
31
+ "b.addEventListener('click',function(){"
32
+ "if(!confirm('Reset all statistics? This cannot be undone.')){return;}"
33
+ "fetch(location.pathname.replace(/\\/+$/,'')+'/reset',"
34
+ "{method:'POST',headers:{'X-Stats-Reset':'1'},credentials:'same-origin'})"
35
+ ".then(function(r){if(r.ok){location.reload();}else{alert('Reset failed: HTTP '+r.status);}})"
36
+ ".catch(function(){alert('Reset failed: network error');});});})();\n"
37
+ )
38
+
39
+
40
+ def _handler(collector: StatsCollector) -> Callable[[Request], Awaitable[Response]]:
41
+ async def reset(request: Request) -> Response:
42
+ if request.headers.get(HEADER) != "1":
43
+ return PlainTextResponse("Missing header X-Stats-Reset: 1", 400)
44
+ try:
45
+ await run_in_threadpool(collector.reset)
46
+ except NotImplementedError:
47
+ return PlainTextResponse("This store does not support reset", 501)
48
+ return Response(status_code=204, headers={"Cache-Control": "no-store"})
49
+
50
+ return reset
51
+
52
+
53
+ def _html_top(collector: StatsCollector) -> str:
54
+ if not collector.config.allow_reset:
55
+ return ""
56
+ return f'<p><button type="button" id="{BUTTON_ID}">Reset statistics</button></p>'
57
+
58
+
59
+ ENDPOINT = EndpointSpec(suffix=SUFFIX, methods=("POST",), enabled=lambda config: config.allow_reset, handler=_handler)
60
+ PART = PagePart(name="reset", html_top=_html_top, js=_JS)