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,73 @@
|
|
|
1
|
+
"""fastapi-perfstats: per-route call statistics, slow-call log and a stats page."""
|
|
2
|
+
|
|
3
|
+
import importlib.metadata
|
|
4
|
+
from typing import Any
|
|
5
|
+
|
|
6
|
+
from fastapi_perfstats.auth import localhost_only
|
|
7
|
+
from fastapi_perfstats.collector import (
|
|
8
|
+
StatsCollector,
|
|
9
|
+
get_default_collector,
|
|
10
|
+
import_route_module,
|
|
11
|
+
set_default_collector,
|
|
12
|
+
)
|
|
13
|
+
from fastapi_perfstats.config import DEFAULT_QUANTILES, AccessCheck, BasicAuth, StatsConfig
|
|
14
|
+
from fastapi_perfstats.middleware import StatsMiddleware
|
|
15
|
+
from fastapi_perfstats.models import (
|
|
16
|
+
CLIENT_CLOSED_STATUS,
|
|
17
|
+
OTHER_KEY,
|
|
18
|
+
OTHER_METHOD,
|
|
19
|
+
UNMATCHED_ROUTE,
|
|
20
|
+
CallRecord,
|
|
21
|
+
RecentStats,
|
|
22
|
+
RouteStats,
|
|
23
|
+
SlowCall,
|
|
24
|
+
SlowExtra,
|
|
25
|
+
)
|
|
26
|
+
from fastapi_perfstats.page import mount_stats, render_html, render_json, stats_router
|
|
27
|
+
from fastapi_perfstats.prometheus import render_prometheus
|
|
28
|
+
from fastapi_perfstats.stores import MemoryStore, SqliteStore, StatsStore
|
|
29
|
+
|
|
30
|
+
try:
|
|
31
|
+
__version__ = importlib.metadata.version("fastapi-perfstats")
|
|
32
|
+
except importlib.metadata.PackageNotFoundError: # pragma: no cover - only when run from an uninstalled checkout
|
|
33
|
+
__version__ = "0+unknown"
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
"CLIENT_CLOSED_STATUS",
|
|
37
|
+
"DEFAULT_QUANTILES",
|
|
38
|
+
"OTHER_KEY",
|
|
39
|
+
"OTHER_METHOD",
|
|
40
|
+
"UNMATCHED_ROUTE",
|
|
41
|
+
"AccessCheck",
|
|
42
|
+
"BasicAuth",
|
|
43
|
+
"CallRecord",
|
|
44
|
+
"MemoryStore",
|
|
45
|
+
"RecentStats",
|
|
46
|
+
"RouteStats",
|
|
47
|
+
"SlowCall",
|
|
48
|
+
"SlowExtra",
|
|
49
|
+
"SqliteStore",
|
|
50
|
+
"StatsCollector",
|
|
51
|
+
"StatsConfig",
|
|
52
|
+
"StatsMiddleware",
|
|
53
|
+
"StatsStore",
|
|
54
|
+
"StatsRoute",
|
|
55
|
+
"__version__",
|
|
56
|
+
"get_default_collector",
|
|
57
|
+
"localhost_only",
|
|
58
|
+
"make_route_class",
|
|
59
|
+
"mount_stats",
|
|
60
|
+
"render_html",
|
|
61
|
+
"render_json",
|
|
62
|
+
"render_prometheus",
|
|
63
|
+
"set_default_collector",
|
|
64
|
+
"stats_router",
|
|
65
|
+
]
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def __getattr__(name: str) -> Any:
|
|
69
|
+
# StatsRoute / make_route_class need fastapi (never a dependency of this package): imported lazily so that
|
|
70
|
+
# `import fastapi_perfstats` keeps working with starlette only.
|
|
71
|
+
if name in ("StatsRoute", "make_route_class"):
|
|
72
|
+
return getattr(import_route_module(), name)
|
|
73
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
@@ -0,0 +1,60 @@
|
|
|
1
|
+
"""Access control for the stats endpoints (owned by #9)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import base64
|
|
6
|
+
import binascii
|
|
7
|
+
import contextlib
|
|
8
|
+
import inspect
|
|
9
|
+
import secrets
|
|
10
|
+
|
|
11
|
+
from starlette.requests import Request
|
|
12
|
+
from starlette.responses import PlainTextResponse, Response
|
|
13
|
+
|
|
14
|
+
from fastapi_perfstats.config import StatsConfig
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def _basic_auth_denied(request: Request, config: StatsConfig) -> Response | None:
|
|
18
|
+
auth = config.credentials
|
|
19
|
+
if auth is None:
|
|
20
|
+
return None
|
|
21
|
+
user, pw = b"", b""
|
|
22
|
+
header = request.headers.get("authorization", "")
|
|
23
|
+
scheme, _, token = header.partition(" ")
|
|
24
|
+
if scheme.lower() == "basic":
|
|
25
|
+
with contextlib.suppress(binascii.Error, ValueError):
|
|
26
|
+
user, _, pw = base64.b64decode(token, validate=True).partition(b":")
|
|
27
|
+
# both compares always run (no short-circuit) so timing does not reveal which part was wrong
|
|
28
|
+
ok_user = secrets.compare_digest(user, auth.username.encode())
|
|
29
|
+
ok_pw = secrets.compare_digest(pw, auth.password.encode())
|
|
30
|
+
if ok_user and ok_pw:
|
|
31
|
+
return None
|
|
32
|
+
return PlainTextResponse("Unauthorized", 401, headers={"WWW-Authenticate": 'Basic realm="stats"'})
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
async def authorize(request: Request, config: StatsConfig) -> Response | None:
|
|
36
|
+
"""``None`` if the request may pass, else the 401 / 403 response to return.
|
|
37
|
+
|
|
38
|
+
Order: HTTP Basic (``config.basic_auth``, 401 on failure), then ``config.access`` (sync or async; a falsy result
|
|
39
|
+
gives 403). Exceptions from ``access`` propagate and are never swallowed.
|
|
40
|
+
"""
|
|
41
|
+
denied = _basic_auth_denied(request, config)
|
|
42
|
+
if denied is not None:
|
|
43
|
+
return denied
|
|
44
|
+
if config.access is None:
|
|
45
|
+
return None
|
|
46
|
+
allowed = config.access(request)
|
|
47
|
+
if inspect.isawaitable(allowed):
|
|
48
|
+
allowed = await allowed
|
|
49
|
+
if allowed:
|
|
50
|
+
return None
|
|
51
|
+
return PlainTextResponse("Forbidden", 403)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def localhost_only(request: Request) -> bool:
|
|
55
|
+
"""``AccessCheck`` allowing loopback clients only (``127.0.0.1`` and ``::1``).
|
|
56
|
+
|
|
57
|
+
Unreliable behind a reverse proxy: the client address is then the proxy's.
|
|
58
|
+
"""
|
|
59
|
+
client = request.client
|
|
60
|
+
return client is not None and client.host in {"127.0.0.1", "::1"}
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"""Collector: ties config + store together and offers the three ways to measure (middleware, route class, decorator)."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import functools
|
|
6
|
+
import importlib
|
|
7
|
+
import time
|
|
8
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
9
|
+
from typing import TYPE_CHECKING, Any
|
|
10
|
+
|
|
11
|
+
from starlette.types import ASGIApp
|
|
12
|
+
|
|
13
|
+
# `ext` must load before `slow_context` (the extension registry imports slow_context back); names load in this order
|
|
14
|
+
from fastapi_perfstats import ext, keys, mounts, slow_context # noqa: F401
|
|
15
|
+
from fastapi_perfstats.config import StatsConfig
|
|
16
|
+
from fastapi_perfstats.middleware import StatsMiddleware
|
|
17
|
+
from fastapi_perfstats.models import CallRecord, SlowExtra
|
|
18
|
+
from fastapi_perfstats.stores import StatsStore, build_store
|
|
19
|
+
|
|
20
|
+
if TYPE_CHECKING: # fastapi is only needed for typing here; the runtime import stays lazy
|
|
21
|
+
from types import ModuleType
|
|
22
|
+
|
|
23
|
+
from fastapi_perfstats.route import StatsRoute
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _is_excluded(path: str, excluded: tuple[str, ...]) -> bool:
|
|
27
|
+
return any(path == p or path.startswith(p.rstrip("/") + "/") for p in excluded if p)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class StatsCollector:
|
|
31
|
+
"""Owns the store. Create one per app and hand it to the middleware / route class / stats router."""
|
|
32
|
+
|
|
33
|
+
def __init__(self, config: StatsConfig | None = None) -> None:
|
|
34
|
+
self.config = config or StatsConfig()
|
|
35
|
+
self.store: StatsStore = build_store(self.config)
|
|
36
|
+
|
|
37
|
+
# -- recording -------------------------------------------------------------------------------------------
|
|
38
|
+
def is_excluded(self, path: str) -> bool:
|
|
39
|
+
return _is_excluded(path, self.config.excluded)
|
|
40
|
+
|
|
41
|
+
def finish(
|
|
42
|
+
self,
|
|
43
|
+
scope: Mapping[str, Any],
|
|
44
|
+
duration_ms: float,
|
|
45
|
+
status: int,
|
|
46
|
+
*,
|
|
47
|
+
request_bytes: int | None = None,
|
|
48
|
+
response_bytes: int | None = None,
|
|
49
|
+
) -> None:
|
|
50
|
+
"""Record one finished request. Call after the app ran: ``scope["route"]`` is filled in by routing."""
|
|
51
|
+
key = keys.build_key(scope, self.config, mounts.mount_prefix(scope)) # key_func, if set, decides there
|
|
52
|
+
if key is None:
|
|
53
|
+
return
|
|
54
|
+
key = key[: self.config.max_key_length]
|
|
55
|
+
threshold = self.config.slow_threshold_for(key)
|
|
56
|
+
slow = threshold is not None and duration_ms >= threshold
|
|
57
|
+
extra = slow_context.capture(scope, self.config, key, duration_ms) if slow else SlowExtra()
|
|
58
|
+
self.record_call(
|
|
59
|
+
CallRecord(
|
|
60
|
+
key=key,
|
|
61
|
+
duration_ms=duration_ms,
|
|
62
|
+
status=status,
|
|
63
|
+
ts=time.time(),
|
|
64
|
+
method=scope.get("method", ""),
|
|
65
|
+
path=scope.get("path", ""),
|
|
66
|
+
request_bytes=request_bytes,
|
|
67
|
+
response_bytes=response_bytes,
|
|
68
|
+
query=extra.query,
|
|
69
|
+
request_id=extra.request_id,
|
|
70
|
+
context=extra.context,
|
|
71
|
+
)
|
|
72
|
+
)
|
|
73
|
+
|
|
74
|
+
def record_call(self, call: CallRecord) -> None:
|
|
75
|
+
self.store.record(call)
|
|
76
|
+
|
|
77
|
+
def record(self, key: str, duration_ms: float, status: int) -> None:
|
|
78
|
+
self.record_call(CallRecord(key=key, duration_ms=duration_ms, status=status, ts=time.time()))
|
|
79
|
+
|
|
80
|
+
def reset(self) -> None:
|
|
81
|
+
"""Forget all statistics (stores that do not support it raise ``NotImplementedError``)."""
|
|
82
|
+
self.store.reset()
|
|
83
|
+
|
|
84
|
+
def close(self) -> None:
|
|
85
|
+
self.store.close()
|
|
86
|
+
|
|
87
|
+
# -- app/router level ------------------------------------------------------------------------------------
|
|
88
|
+
@property
|
|
89
|
+
def middleware(self) -> Callable[[ASGIApp], ASGIApp]:
|
|
90
|
+
"""``app.add_middleware(collector.middleware)``-friendly class bound to this collector."""
|
|
91
|
+
collector = self
|
|
92
|
+
|
|
93
|
+
class _Bound(StatsMiddleware):
|
|
94
|
+
def __init__(self, app: ASGIApp) -> None:
|
|
95
|
+
super().__init__(app, collector)
|
|
96
|
+
|
|
97
|
+
return _Bound
|
|
98
|
+
|
|
99
|
+
# -- single routes ---------------------------------------------------------------------------------------
|
|
100
|
+
@property
|
|
101
|
+
def route_class(self) -> type[StatsRoute]:
|
|
102
|
+
"""``APIRouter(route_class=collector.route_class)`` or ``@router.get(..., route_class_override=...)``."""
|
|
103
|
+
route_cls: type[StatsRoute] = import_route_module().make_route_class(self)
|
|
104
|
+
return route_cls
|
|
105
|
+
|
|
106
|
+
def track(
|
|
107
|
+
self, name: str | None = None
|
|
108
|
+
) -> Callable[[Callable[..., Awaitable[Any]]], Callable[..., Awaitable[Any]]]:
|
|
109
|
+
"""Decorator for one async endpoint: ``@app.get("/x")`` on top, ``@collector.track()`` below it."""
|
|
110
|
+
|
|
111
|
+
def deco(fn: Callable[..., Awaitable[Any]]) -> Callable[..., Awaitable[Any]]:
|
|
112
|
+
label = name or fn.__name__
|
|
113
|
+
|
|
114
|
+
@functools.wraps(fn)
|
|
115
|
+
async def wrapper(*args: Any, **kwargs: Any) -> Any:
|
|
116
|
+
start = time.perf_counter()
|
|
117
|
+
status = 200
|
|
118
|
+
try:
|
|
119
|
+
result = await fn(*args, **kwargs)
|
|
120
|
+
status = getattr(result, "status_code", 200)
|
|
121
|
+
return result
|
|
122
|
+
except Exception as exc:
|
|
123
|
+
status = getattr(exc, "status_code", 500)
|
|
124
|
+
raise
|
|
125
|
+
finally:
|
|
126
|
+
self.record_call(
|
|
127
|
+
CallRecord(
|
|
128
|
+
key=label, duration_ms=(time.perf_counter() - start) * 1000, status=status, ts=time.time()
|
|
129
|
+
)
|
|
130
|
+
)
|
|
131
|
+
|
|
132
|
+
return wrapper
|
|
133
|
+
|
|
134
|
+
return deco
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def import_route_module() -> ModuleType:
|
|
138
|
+
"""Import ``fastapi_perfstats.route`` (needs FastAPI) with a clear error if FastAPI is missing."""
|
|
139
|
+
try:
|
|
140
|
+
return importlib.import_module("fastapi_perfstats.route")
|
|
141
|
+
except ImportError as exc:
|
|
142
|
+
raise ImportError("StatsRoute needs FastAPI installed (pip install fastapi)") from exc
|
|
143
|
+
|
|
144
|
+
|
|
145
|
+
_default: StatsCollector | None = None
|
|
146
|
+
|
|
147
|
+
|
|
148
|
+
def set_default_collector(collector: StatsCollector | None) -> None:
|
|
149
|
+
"""Set (or with ``None`` reset) the process-wide collector used by the plain ``StatsRoute`` class."""
|
|
150
|
+
global _default
|
|
151
|
+
_default = collector
|
|
152
|
+
|
|
153
|
+
|
|
154
|
+
def get_default_collector() -> StatsCollector:
|
|
155
|
+
"""The process-wide collector; created with a default ``StatsConfig`` on first use."""
|
|
156
|
+
global _default
|
|
157
|
+
if _default is None:
|
|
158
|
+
_default = StatsCollector()
|
|
159
|
+
return _default
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
"""Single configuration object for fastapi-perfstats."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import re
|
|
6
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from types import MappingProxyType
|
|
9
|
+
from typing import Any, Literal
|
|
10
|
+
|
|
11
|
+
from starlette.requests import Request
|
|
12
|
+
|
|
13
|
+
DEFAULT_QUANTILES: tuple[float, ...] = (0.5, 0.95, 0.99)
|
|
14
|
+
|
|
15
|
+
KeyFunc = Callable[[Mapping[str, Any]], "str | None"]
|
|
16
|
+
AccessCheck = Callable[[Request], "bool | Awaitable[bool]"]
|
|
17
|
+
SlowContextFunc = Callable[[Mapping[str, Any]], Mapping[str, str]]
|
|
18
|
+
|
|
19
|
+
_PROMETHEUS_NAME = re.compile(r"[a-zA-Z_:][a-zA-Z0-9_:]*")
|
|
20
|
+
_REFRESH_CHOICES = (None, 0, 5, 15, 60)
|
|
21
|
+
_UNMATCHED_CHOICES = ("group", "raw", "skip")
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
@dataclass(frozen=True)
|
|
25
|
+
class BasicAuth:
|
|
26
|
+
"""HTTP Basic credentials for the stats page. The password is hidden from ``repr`` and never logged."""
|
|
27
|
+
|
|
28
|
+
username: str
|
|
29
|
+
password: str = field(repr=False)
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass(frozen=True)
|
|
33
|
+
class StatsConfig:
|
|
34
|
+
"""All knobs in one place.
|
|
35
|
+
|
|
36
|
+
quantiles: percentiles shown/exported, values in (0, 1]. Custom values *replace* the defaults.
|
|
37
|
+
storage: ``"memory"`` (default), ``"sqlite"`` or any object implementing ``StatsStore``.
|
|
38
|
+
sqlite_path: database file used when ``storage="sqlite"``.
|
|
39
|
+
window_size: durations kept per route (ring buffer); quantiles are computed on this window.
|
|
40
|
+
max_routes: distinct keys kept; further new keys are merged into the ``"other"`` bucket.
|
|
41
|
+
slow_threshold_ms: calls taking at least this long are logged individually; ``None`` disables the log.
|
|
42
|
+
max_slow_calls: size of the slow-call log; when full the oldest entry is dropped (most recent N kept).
|
|
43
|
+
stats_path: URL of the HTML page (JSON lives at ``stats_path + ".json"``).
|
|
44
|
+
exclude_paths: raw request paths (and their sub-paths) that are never counted. ``stats_path`` and
|
|
45
|
+
its JSON twin are always excluded.
|
|
46
|
+
key_func: optional ``scope -> key`` (or ``None`` to skip the call), called after the request finished.
|
|
47
|
+
basic_auth: ``(user, password)`` or ``BasicAuth``; protects the HTML page and the JSON endpoint
|
|
48
|
+
(``secrets.compare_digest``, 401 + ``WWW-Authenticate``). ``None`` = no auth (a warning is logged on mount).
|
|
49
|
+
max_key_length: keys longer than this are truncated (defence against huge raw paths).
|
|
50
|
+
unmatched: how requests without a matching route are keyed: ``"group"``, ``"raw"`` or ``"skip"`` (#5).
|
|
51
|
+
close_on_shutdown: close the store when the app shuts down (#7).
|
|
52
|
+
access: optional extra access check ``request -> bool`` (may be async) for the stats endpoints (#9).
|
|
53
|
+
allow_reset: enable the reset endpoint (#10).
|
|
54
|
+
slow_thresholds: per-key slow thresholds in ms (``None`` = never slow); keys non-empty, values >= 0 (#12).
|
|
55
|
+
slow_capture_query: store the (redacted) query string with slow calls (#13).
|
|
56
|
+
redact_query_params: query parameter name fragments whose values are redacted; lower-cased (#13).
|
|
57
|
+
slow_request_id_headers: request headers tried in order for a request id; lower-cased (#13).
|
|
58
|
+
slow_context: optional ``scope -> {name: value}`` hook adding context to slow calls (#13).
|
|
59
|
+
track_sizes: track request/response payload sizes (#6, #14).
|
|
60
|
+
recent_minutes: minutes of recent activity kept, 0..1440; 0 disables (#15).
|
|
61
|
+
recent_windows: recent windows in minutes, each 1..recent_minutes; sorted, unique (#15).
|
|
62
|
+
refresh_seconds: live page refresh interval: ``None``, 0, 5, 15 or 60 (#16).
|
|
63
|
+
prometheus: enable the Prometheus text endpoint (#17).
|
|
64
|
+
prometheus_prefix: metric name prefix, ``[a-zA-Z_:][a-zA-Z0-9_:]*`` (#17).
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
quantiles: tuple[float, ...] = DEFAULT_QUANTILES
|
|
68
|
+
storage: Any = "memory"
|
|
69
|
+
sqlite_path: str = "fastapi_perfstats.db"
|
|
70
|
+
window_size: int = 1000
|
|
71
|
+
max_routes: int = 200
|
|
72
|
+
slow_threshold_ms: float | None = 500.0
|
|
73
|
+
max_slow_calls: int = 200
|
|
74
|
+
stats_path: str = "/stats"
|
|
75
|
+
exclude_paths: tuple[str, ...] = ("/health",)
|
|
76
|
+
key_func: KeyFunc | None = None
|
|
77
|
+
max_key_length: int = 200
|
|
78
|
+
basic_auth: BasicAuth | tuple[str, str] | None = None
|
|
79
|
+
unmatched: Literal["group", "raw", "skip"] = "group"
|
|
80
|
+
close_on_shutdown: bool = True
|
|
81
|
+
access: AccessCheck | None = None
|
|
82
|
+
allow_reset: bool = False
|
|
83
|
+
slow_thresholds: Mapping[str, float | None] = field(default_factory=dict)
|
|
84
|
+
slow_capture_query: bool = False
|
|
85
|
+
redact_query_params: tuple[str, ...] = ("pass", "tok", "secret", "key", "auth", "sig", "session", "code")
|
|
86
|
+
slow_request_id_headers: tuple[str, ...] = ("x-request-id", "traceparent")
|
|
87
|
+
slow_context: SlowContextFunc | None = None
|
|
88
|
+
track_sizes: bool = True
|
|
89
|
+
recent_minutes: int = 60
|
|
90
|
+
recent_windows: tuple[int, ...] = (1, 5, 15)
|
|
91
|
+
refresh_seconds: int | None = None
|
|
92
|
+
prometheus: bool = False
|
|
93
|
+
prometheus_prefix: str = "fastapi_perfstats"
|
|
94
|
+
|
|
95
|
+
def __post_init__(self) -> None:
|
|
96
|
+
if isinstance(self.basic_auth, tuple):
|
|
97
|
+
object.__setattr__(self, "basic_auth", BasicAuth(*self.basic_auth))
|
|
98
|
+
if not self.quantiles or any(not 0 < q <= 1 for q in self.quantiles):
|
|
99
|
+
raise ValueError("quantiles must be a non-empty sequence of values in (0, 1]")
|
|
100
|
+
object.__setattr__(self, "quantiles", tuple(sorted(set(self.quantiles))))
|
|
101
|
+
for name in ("window_size", "max_routes", "max_slow_calls", "max_key_length"):
|
|
102
|
+
if getattr(self, name) < 1:
|
|
103
|
+
raise ValueError(f"{name} must be >= 1")
|
|
104
|
+
if self.slow_threshold_ms is not None and self.slow_threshold_ms < 0:
|
|
105
|
+
raise ValueError("slow_threshold_ms must be >= 0 or None")
|
|
106
|
+
if not self.stats_path.startswith("/"):
|
|
107
|
+
raise ValueError("stats_path must start with '/'")
|
|
108
|
+
if self.unmatched not in _UNMATCHED_CHOICES:
|
|
109
|
+
raise ValueError("unmatched must be one of 'group', 'raw', 'skip'")
|
|
110
|
+
if any(not key for key in self.slow_thresholds):
|
|
111
|
+
raise ValueError("slow_thresholds keys must be non-empty")
|
|
112
|
+
if any(v is not None and v < 0 for v in self.slow_thresholds.values()):
|
|
113
|
+
raise ValueError("slow_thresholds values must be >= 0 or None")
|
|
114
|
+
object.__setattr__(self, "slow_thresholds", MappingProxyType(dict(self.slow_thresholds)))
|
|
115
|
+
object.__setattr__(self, "redact_query_params", tuple(p.lower() for p in self.redact_query_params))
|
|
116
|
+
object.__setattr__(self, "slow_request_id_headers", tuple(h.lower() for h in self.slow_request_id_headers))
|
|
117
|
+
if not 0 <= self.recent_minutes <= 1440:
|
|
118
|
+
raise ValueError("recent_minutes must be between 0 and 1440")
|
|
119
|
+
if self.recent_minutes and any(not 1 <= w <= self.recent_minutes for w in self.recent_windows):
|
|
120
|
+
raise ValueError("recent_windows values must be between 1 and recent_minutes")
|
|
121
|
+
object.__setattr__(self, "recent_windows", tuple(sorted(set(self.recent_windows))))
|
|
122
|
+
if self.refresh_seconds not in _REFRESH_CHOICES:
|
|
123
|
+
raise ValueError("refresh_seconds must be None, 0, 5, 15 or 60")
|
|
124
|
+
if not _PROMETHEUS_NAME.fullmatch(self.prometheus_prefix):
|
|
125
|
+
raise ValueError("prometheus_prefix must match [a-zA-Z_:][a-zA-Z0-9_:]*")
|
|
126
|
+
|
|
127
|
+
def slow_threshold_for(self, key: str) -> float | None:
|
|
128
|
+
"""Slow threshold in ms for ``key`` (``None`` = never slow).
|
|
129
|
+
|
|
130
|
+
Lookup order, plain dict lookups only: the exact key (``"GET /a/{id}"``), then the route part without the
|
|
131
|
+
method (``"/a/{id}"``, any method), then the global ``slow_threshold_ms``. An override of ``None``
|
|
132
|
+
disables the slow log for that route.
|
|
133
|
+
"""
|
|
134
|
+
if key in self.slow_thresholds:
|
|
135
|
+
return self.slow_thresholds[key]
|
|
136
|
+
route = key.partition(" ")[2]
|
|
137
|
+
if route in self.slow_thresholds:
|
|
138
|
+
return self.slow_thresholds[route]
|
|
139
|
+
return self.slow_threshold_ms
|
|
140
|
+
|
|
141
|
+
def slow_threshold_summary(self) -> str:
|
|
142
|
+
"""Heading text for the slow-call table, e.g. ``">= 500 ms, 2 route overrides"``."""
|
|
143
|
+
text = "disabled" if self.slow_threshold_ms is None else f">= {self.slow_threshold_ms:g} ms"
|
|
144
|
+
n = len(self.slow_thresholds)
|
|
145
|
+
if n:
|
|
146
|
+
text += f", {n} route override{'' if n == 1 else 's'}"
|
|
147
|
+
return text
|
|
148
|
+
|
|
149
|
+
@property
|
|
150
|
+
def credentials(self) -> BasicAuth | None:
|
|
151
|
+
"""``basic_auth`` normalised to a ``BasicAuth`` (the tuple form is converted in ``__post_init__``)."""
|
|
152
|
+
auth = self.basic_auth
|
|
153
|
+
return BasicAuth(*auth) if isinstance(auth, tuple) else auth
|
|
154
|
+
|
|
155
|
+
@property
|
|
156
|
+
def excluded(self) -> tuple[str, ...]:
|
|
157
|
+
base = self.stats_path.rstrip("/")
|
|
158
|
+
return (*self.exclude_paths, base, base + ".json")
|
|
159
|
+
|
|
160
|
+
|
|
161
|
+
def quantile_label(q: float) -> str:
|
|
162
|
+
"""0.95 -> ``p95``, 0.999 -> ``p99.9``."""
|
|
163
|
+
return f"p{q * 100:g}"
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
"""Registry of statistics extensions, in fixed order."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from fastapi_perfstats import live, slow_context
|
|
6
|
+
from fastapi_perfstats.ext import recent, sizes, stddev
|
|
7
|
+
from fastapi_perfstats.ext.base import Extension
|
|
8
|
+
|
|
9
|
+
EXTENSIONS: tuple[Extension, ...] = (stddev.EXT, sizes.EXT, recent.EXT, slow_context.EXT, live.EXT)
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""Extension protocol, column / page-part / endpoint descriptions and the no-op base extension."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import sqlite3
|
|
6
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
7
|
+
from dataclasses import dataclass
|
|
8
|
+
from typing import TYPE_CHECKING, Any, Literal, Protocol
|
|
9
|
+
|
|
10
|
+
from starlette.requests import Request
|
|
11
|
+
from starlette.responses import Response
|
|
12
|
+
|
|
13
|
+
from fastapi_perfstats.config import StatsConfig
|
|
14
|
+
from fastapi_perfstats.models import CallRecord, RouteStats
|
|
15
|
+
|
|
16
|
+
if TYPE_CHECKING:
|
|
17
|
+
from fastapi_perfstats.collector import StatsCollector
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
@dataclass(frozen=True)
|
|
21
|
+
class Column:
|
|
22
|
+
table: Literal["freq", "rt", "slow", "sizes"]
|
|
23
|
+
header: str
|
|
24
|
+
order: int
|
|
25
|
+
cell: Callable[[Any, StatsConfig], tuple[str, float | None]] # (RouteStats or SlowCall, config) -> (text, sort)
|
|
26
|
+
raw_html: bool = False # True only for trusted markup (sparklines); text is escaped otherwise
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
@dataclass(frozen=True)
|
|
30
|
+
class PagePart:
|
|
31
|
+
name: str
|
|
32
|
+
html_top: Callable[[StatsCollector], str] # trusted HTML after the intro paragraph; escapes its own data
|
|
33
|
+
js: str = "" # static script appended to the page script (CSP hash)
|
|
34
|
+
body_attrs: Callable[[StatsConfig], dict[str, str]] = lambda config: {} # data-* on <body>; values escaped
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class EndpointSpec:
|
|
39
|
+
suffix: str # e.g. "/reset", appended to stats_path
|
|
40
|
+
methods: tuple[str, ...]
|
|
41
|
+
enabled: Callable[[StatsConfig], bool]
|
|
42
|
+
handler: Callable[[StatsCollector], Callable[[Request], Awaitable[Response]]] # auth/headers added by router
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
class Extension(Protocol):
|
|
46
|
+
"""Hooks a feature can implement; ``call.key`` is always the final key (after ``other`` bucketing).
|
|
47
|
+
|
|
48
|
+
SQLite hooks run inside the writer's transaction and must not commit.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
name: str
|
|
52
|
+
|
|
53
|
+
def sqlite_schema(self) -> tuple[str, ...]: ... # idempotent CREATE TABLE/INDEX IF NOT EXISTS
|
|
54
|
+
|
|
55
|
+
def memory_update(self, state: dict[str, Any], call: CallRecord) -> None: ...
|
|
56
|
+
|
|
57
|
+
def memory_finish(self, row: RouteStats, state: dict[str, Any], config: StatsConfig, now: float) -> None: ...
|
|
58
|
+
|
|
59
|
+
def sqlite_update(self, db: sqlite3.Connection, call: CallRecord) -> None: ...
|
|
60
|
+
|
|
61
|
+
def sqlite_prune(self, db: sqlite3.Connection, config: StatsConfig, now: float) -> None: ...
|
|
62
|
+
|
|
63
|
+
def sqlite_finish(
|
|
64
|
+
self, rows: Mapping[str, RouteStats], db: sqlite3.Connection, config: StatsConfig, now: float
|
|
65
|
+
) -> None: ...
|
|
66
|
+
|
|
67
|
+
def sqlite_reset(self, db: sqlite3.Connection) -> None: ...
|
|
68
|
+
|
|
69
|
+
def columns(self, config: StatsConfig) -> tuple[Column, ...]: ...
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class NoopExtension:
|
|
73
|
+
"""Implements ``Extension`` with no-ops; feature extensions subclass it or are created with their name."""
|
|
74
|
+
|
|
75
|
+
def __init__(self, name: str = "noop") -> None:
|
|
76
|
+
self.name = name
|
|
77
|
+
|
|
78
|
+
def sqlite_schema(self) -> tuple[str, ...]:
|
|
79
|
+
return ()
|
|
80
|
+
|
|
81
|
+
def memory_update(self, state: dict[str, Any], call: CallRecord) -> None:
|
|
82
|
+
return None
|
|
83
|
+
|
|
84
|
+
def memory_finish(self, row: RouteStats, state: dict[str, Any], config: StatsConfig, now: float) -> None:
|
|
85
|
+
return None
|
|
86
|
+
|
|
87
|
+
def sqlite_update(self, db: sqlite3.Connection, call: CallRecord) -> None:
|
|
88
|
+
return None
|
|
89
|
+
|
|
90
|
+
def sqlite_prune(self, db: sqlite3.Connection, config: StatsConfig, now: float) -> None:
|
|
91
|
+
return None
|
|
92
|
+
|
|
93
|
+
def sqlite_finish(
|
|
94
|
+
self, rows: Mapping[str, RouteStats], db: sqlite3.Connection, config: StatsConfig, now: float
|
|
95
|
+
) -> None:
|
|
96
|
+
return None
|
|
97
|
+
|
|
98
|
+
def sqlite_reset(self, db: sqlite3.Connection) -> None:
|
|
99
|
+
return None
|
|
100
|
+
|
|
101
|
+
def columns(self, config: StatsConfig) -> tuple[Column, ...]:
|
|
102
|
+
return ()
|