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