fastapi-redline 0.2.0a1__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_redline/__init__.py +38 -0
- fastapi_redline/_httpx.py +5 -0
- fastapi_redline/_middleware.py +264 -0
- fastapi_redline/_security.py +228 -0
- fastapi_redline/_serialize.py +108 -0
- fastapi_redline/_sqlalchemy.py +19 -0
- fastapi_redline/integration.py +236 -0
- fastapi_redline/py.typed +0 -0
- fastapi_redline/router.py +165 -0
- fastapi_redline/suggest.py +5 -0
- fastapi_redline-0.2.0a1.dist-info/METADATA +267 -0
- fastapi_redline-0.2.0a1.dist-info/RECORD +14 -0
- fastapi_redline-0.2.0a1.dist-info/WHEEL +4 -0
- fastapi_redline-0.2.0a1.dist-info/licenses/LICENSE +21 -0
|
@@ -0,0 +1,236 @@
|
|
|
1
|
+
"""``install(app, ...)``: wire Redline into a FastAPI/Starlette application."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import contextlib
|
|
7
|
+
import logging
|
|
8
|
+
import re
|
|
9
|
+
from collections.abc import Callable, Mapping, Sequence
|
|
10
|
+
from typing import Any
|
|
11
|
+
|
|
12
|
+
from fastapi import Depends, FastAPI
|
|
13
|
+
from fastapi.params import Depends as DependsParam
|
|
14
|
+
|
|
15
|
+
from redline_core import Recorder, Settings, configure
|
|
16
|
+
from redline_core.access import Access
|
|
17
|
+
from redline_core.api import RedlineAPI
|
|
18
|
+
from redline_core.config import ResolvedConfig, resolve_settings
|
|
19
|
+
from redline_core.explain import ExplainExecutor
|
|
20
|
+
from redline_core.load.control import run_hooks
|
|
21
|
+
from redline_core.storage import SQLiteStore, Store
|
|
22
|
+
|
|
23
|
+
from ._middleware import RedlineMiddleware
|
|
24
|
+
from ._security import redline_guard, refuse_false, scope_info
|
|
25
|
+
from ._serialize import instrument_serialization
|
|
26
|
+
from ._sqlalchemy import (
|
|
27
|
+
EngineLike,
|
|
28
|
+
alias_for,
|
|
29
|
+
build_executor,
|
|
30
|
+
instrument_engine,
|
|
31
|
+
name_engines,
|
|
32
|
+
vendor_of,
|
|
33
|
+
)
|
|
34
|
+
from .router import build_router
|
|
35
|
+
from .suggest import SQLAlchemyFixSuggester
|
|
36
|
+
|
|
37
|
+
__all__ = ["Redline", "install"]
|
|
38
|
+
|
|
39
|
+
logger = logging.getLogger("redline")
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _guard_prefix(routes: Sequence[Any], prefix: str) -> None:
|
|
43
|
+
"""Make Redline's routes cost one ``str.startswith`` for every other request.
|
|
44
|
+
|
|
45
|
+
They sit first in the app's route list (so they win over catch-all routes), and
|
|
46
|
+
FastAPI's own matching of an included router walks each of its routes; this skips
|
|
47
|
+
that walk unless the path is under ``prefix``. Each route keeps its type, so
|
|
48
|
+
``isinstance`` checks in FastAPI (OpenAPI, ``url_path_for``…) see it unchanged.
|
|
49
|
+
"""
|
|
50
|
+
from starlette.routing import Match
|
|
51
|
+
|
|
52
|
+
under = prefix + "/"
|
|
53
|
+
|
|
54
|
+
for route in routes:
|
|
55
|
+
original = route.matches
|
|
56
|
+
|
|
57
|
+
def matches(scope: Any, _original: Any = original) -> Any:
|
|
58
|
+
path = scope.get("path", "")
|
|
59
|
+
if path != prefix and not path.startswith(under):
|
|
60
|
+
root = scope.get("root_path", "")
|
|
61
|
+
if not root or not path.startswith(root):
|
|
62
|
+
return Match.NONE, {}
|
|
63
|
+
path = path[len(root) :]
|
|
64
|
+
if path != prefix and not path.startswith(under):
|
|
65
|
+
return Match.NONE, {}
|
|
66
|
+
return _original(scope)
|
|
67
|
+
|
|
68
|
+
try:
|
|
69
|
+
route.matches = matches
|
|
70
|
+
except AttributeError: # pragma: no cover - a route type with __slots__
|
|
71
|
+
pass
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
class Redline:
|
|
75
|
+
"""The handle ``install()`` returns."""
|
|
76
|
+
|
|
77
|
+
def __init__(
|
|
78
|
+
self,
|
|
79
|
+
*,
|
|
80
|
+
app: FastAPI,
|
|
81
|
+
prefix: str,
|
|
82
|
+
settings: Settings,
|
|
83
|
+
recorder: Recorder,
|
|
84
|
+
store: Store,
|
|
85
|
+
suggester: SQLAlchemyFixSuggester,
|
|
86
|
+
config: ResolvedConfig | None = None,
|
|
87
|
+
access: Access | None = None,
|
|
88
|
+
) -> None:
|
|
89
|
+
self.app = app
|
|
90
|
+
self.prefix = prefix
|
|
91
|
+
self.settings = settings
|
|
92
|
+
self.recorder = recorder
|
|
93
|
+
self.store = store
|
|
94
|
+
self.suggester = suggester
|
|
95
|
+
self.config = config
|
|
96
|
+
self.access = access if access is not None else Access(settings)
|
|
97
|
+
self.engines: dict[str, EngineLike] = {}
|
|
98
|
+
self.loop: asyncio.AbstractEventLoop | None = None
|
|
99
|
+
launcher, stopper = run_hooks(store, settings)
|
|
100
|
+
self.api = RedlineAPI(
|
|
101
|
+
store,
|
|
102
|
+
settings,
|
|
103
|
+
framework="fastapi",
|
|
104
|
+
explain_executor=self._executor_for,
|
|
105
|
+
run_launcher=launcher,
|
|
106
|
+
run_stopper=stopper,
|
|
107
|
+
config=config,
|
|
108
|
+
access=self.access,
|
|
109
|
+
)
|
|
110
|
+
|
|
111
|
+
def add_engine(self, engine: EngineLike, alias: str | None = None) -> str:
|
|
112
|
+
"""Instrument another engine; returns its ``db_alias``."""
|
|
113
|
+
if alias is None:
|
|
114
|
+
alias = alias_for(engine, self.engines)
|
|
115
|
+
self.engines[alias] = engine
|
|
116
|
+
if self.settings.enabled:
|
|
117
|
+
instrument_engine(engine, alias)
|
|
118
|
+
return alias
|
|
119
|
+
|
|
120
|
+
def _executor_for(self, alias: str, vendor: str) -> ExplainExecutor | None:
|
|
121
|
+
engine = self.engines.get(alias)
|
|
122
|
+
if engine is None:
|
|
123
|
+
return None
|
|
124
|
+
return build_executor(engine, vendor_of(engine), lambda: self.loop)
|
|
125
|
+
|
|
126
|
+
def close(self) -> None:
|
|
127
|
+
"""Flush pending traces and close the store (called on app shutdown)."""
|
|
128
|
+
with contextlib.suppress(Exception):
|
|
129
|
+
self.store.flush(5.0)
|
|
130
|
+
self.store.close()
|
|
131
|
+
|
|
132
|
+
|
|
133
|
+
def install(
|
|
134
|
+
app: FastAPI,
|
|
135
|
+
*,
|
|
136
|
+
engine: Any = None,
|
|
137
|
+
settings: Mapping[str, Any] | Settings | None = None,
|
|
138
|
+
prefix: str | None = None,
|
|
139
|
+
dependencies: Sequence[Callable[..., Any] | DependsParam] | None = None,
|
|
140
|
+
models: Any = None,
|
|
141
|
+
store: Store | None = None,
|
|
142
|
+
) -> Redline:
|
|
143
|
+
"""Install Redline on ``app``.
|
|
144
|
+
|
|
145
|
+
``engine``
|
|
146
|
+
A sync ``Engine``, an ``AsyncEngine``, a list of them, or ``{alias: engine}``.
|
|
147
|
+
The first of a list is the ``"default"`` db alias (used by EXPLAIN).
|
|
148
|
+
``settings``
|
|
149
|
+
A ``Settings`` or a dict of settings (case-insensitive keys). They are the top
|
|
150
|
+
layer over ``redline.toml`` / ``[tool.redline]`` and ``REDLINE_*`` variables
|
|
151
|
+
(``redline_core.config``).
|
|
152
|
+
``prefix``
|
|
153
|
+
Where the UI and API live (default: the ``mount_path`` setting, else
|
|
154
|
+
``/_redline``). Never recorded.
|
|
155
|
+
``dependencies``
|
|
156
|
+
FastAPI dependencies protecting the UI and API, e.g.
|
|
157
|
+
``[Depends(require_admin)]``; giving them implies ``access="framework"`` unless
|
|
158
|
+
the ``access`` setting is set explicitly. When omitted, the ``access`` setting
|
|
159
|
+
decides. ``[]`` is the same as omitting it. Refuse by raising ``HTTPException``
|
|
160
|
+
(answered in the API's error shape); a dependency that *returns* ``False`` is
|
|
161
|
+
refused with 403 too. When ``access`` is not set at all, Redline answers 404
|
|
162
|
+
unless ``app.debug`` is on (then ``local``: loopback clients addressing
|
|
163
|
+
``localhost``/``127.0.0.1``/``[::1]``).
|
|
164
|
+
``models``
|
|
165
|
+
Declarative ``Base``/``registry`` (or a list) for fix suggestions; by default every
|
|
166
|
+
registry SQLAlchemy knows about.
|
|
167
|
+
``store``
|
|
168
|
+
A custom ``Store``; default is the SQLite file at ``storage_path``.
|
|
169
|
+
"""
|
|
170
|
+
if getattr(app.state, "redline", None) is not None:
|
|
171
|
+
raise RuntimeError("Redline is already installed on this app.")
|
|
172
|
+
# An empty list is no hook at all: the normal default rules apply, not "framework"
|
|
173
|
+
# with nothing to check.
|
|
174
|
+
resolved = resolve_settings(settings, native_hook=bool(dependencies))
|
|
175
|
+
cfg = resolved.settings
|
|
176
|
+
prefix = prefix if prefix is not None else (cfg.mount_path or "/_redline")
|
|
177
|
+
prefix = "/" + prefix.strip("/")
|
|
178
|
+
if prefix == "/":
|
|
179
|
+
raise ValueError("prefix must be a sub-path such as '/_redline'.")
|
|
180
|
+
own = rf"^{re.escape(prefix)}(/|$)"
|
|
181
|
+
if own not in cfg.ignore_paths:
|
|
182
|
+
cfg = cfg.replace(ignore_paths=[*cfg.ignore_paths, own])
|
|
183
|
+
access = Access(cfg, access_explicit=resolved.access_explicit, debug=lambda: bool(app.debug))
|
|
184
|
+
|
|
185
|
+
store = store if store is not None else SQLiteStore.from_settings(cfg)
|
|
186
|
+
suggester = SQLAlchemyFixSuggester(models, project_root=cfg.project_root)
|
|
187
|
+
recorder = configure(cfg, store, [suggester])
|
|
188
|
+
redline = Redline(
|
|
189
|
+
app=app,
|
|
190
|
+
prefix=prefix,
|
|
191
|
+
settings=cfg,
|
|
192
|
+
recorder=recorder,
|
|
193
|
+
store=store,
|
|
194
|
+
suggester=suggester,
|
|
195
|
+
config=resolved,
|
|
196
|
+
access=access,
|
|
197
|
+
)
|
|
198
|
+
for alias, eng in name_engines(engine).items():
|
|
199
|
+
redline.add_engine(eng, alias)
|
|
200
|
+
|
|
201
|
+
deps: list[Any] = [Depends(redline_guard(access, prefix))]
|
|
202
|
+
if dependencies:
|
|
203
|
+
deps.append(refuse_false(dependencies))
|
|
204
|
+
access.log_startup(prefix, "pass install(app, dependencies=[...])")
|
|
205
|
+
|
|
206
|
+
router = build_router(redline, deps)
|
|
207
|
+
before = len(app.router.routes)
|
|
208
|
+
app.include_router(router, prefix=prefix)
|
|
209
|
+
added = app.router.routes[before:]
|
|
210
|
+
del app.router.routes[before:]
|
|
211
|
+
_guard_prefix(added, prefix)
|
|
212
|
+
app.router.routes[0:0] = added # win over catch-all routes declared earlier
|
|
213
|
+
|
|
214
|
+
if cfg.enabled: # disabled: no middleware and no SQLAlchemy listeners at all
|
|
215
|
+
app.add_middleware(
|
|
216
|
+
RedlineMiddleware,
|
|
217
|
+
recorder=recorder,
|
|
218
|
+
prefix=prefix,
|
|
219
|
+
debug=lambda: bool(app.debug),
|
|
220
|
+
force_ok=lambda scope: access.may_force(scope_info(scope), debug=bool(app.debug)),
|
|
221
|
+
)
|
|
222
|
+
instrument_serialization()
|
|
223
|
+
|
|
224
|
+
original = app.router.lifespan_context
|
|
225
|
+
|
|
226
|
+
@contextlib.asynccontextmanager
|
|
227
|
+
async def lifespan(a: Any):
|
|
228
|
+
async with original(a) as state:
|
|
229
|
+
try:
|
|
230
|
+
yield state
|
|
231
|
+
finally:
|
|
232
|
+
await asyncio.to_thread(redline.close)
|
|
233
|
+
|
|
234
|
+
app.router.lifespan_context = lifespan
|
|
235
|
+
app.state.redline = redline
|
|
236
|
+
return redline
|
fastapi_redline/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,165 @@
|
|
|
1
|
+
"""The UI + JSON API router mounted under ``prefix``."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
from collections.abc import Callable, Coroutine, Sequence
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from fastapi import APIRouter, HTTPException, Request, Response
|
|
10
|
+
from fastapi.concurrency import run_in_threadpool
|
|
11
|
+
from fastapi.responses import FileResponse, HTMLResponse, JSONResponse, StreamingResponse
|
|
12
|
+
from fastapi.routing import APIRoute
|
|
13
|
+
|
|
14
|
+
from redline_core import stream, ui
|
|
15
|
+
from redline_core.api import RawResponse, own_base_url
|
|
16
|
+
from redline_core.storage import FilterError
|
|
17
|
+
|
|
18
|
+
from ._security import RedlineHTTPError, request_info
|
|
19
|
+
|
|
20
|
+
__all__ = ["RedlineRoute", "build_router", "error_response"]
|
|
21
|
+
|
|
22
|
+
_NO_STORE = {"Cache-Control": "no-store"}
|
|
23
|
+
_IMMUTABLE = {"Cache-Control": "public, max-age=31536000, immutable"}
|
|
24
|
+
_SECURITY = {
|
|
25
|
+
"X-Content-Type-Options": "nosniff",
|
|
26
|
+
"Referrer-Policy": "same-origin",
|
|
27
|
+
"X-Frame-Options": "DENY",
|
|
28
|
+
}
|
|
29
|
+
_CODES = {
|
|
30
|
+
400: "bad_request",
|
|
31
|
+
401: "unauthorized",
|
|
32
|
+
403: "forbidden",
|
|
33
|
+
404: "not_found",
|
|
34
|
+
405: "method_not_allowed",
|
|
35
|
+
429: "too_many_requests",
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def error_response(
|
|
40
|
+
status: int,
|
|
41
|
+
code: str,
|
|
42
|
+
message: str,
|
|
43
|
+
headers: dict[str, str] | None = None,
|
|
44
|
+
extra: dict[str, Any] | None = None,
|
|
45
|
+
) -> JSONResponse:
|
|
46
|
+
"""A JSON error in the API's shape (``CONTRACT.md`` §5)."""
|
|
47
|
+
return JSONResponse(
|
|
48
|
+
{"error": {"code": code, "message": message, **(extra or {})}},
|
|
49
|
+
status_code=status,
|
|
50
|
+
headers={**_NO_STORE, **_SECURITY, **(headers or {})},
|
|
51
|
+
)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
class RedlineRoute(APIRoute):
|
|
55
|
+
"""Renders ``HTTPException`` – from Redline's guards *and* your auth dependencies –
|
|
56
|
+
as ``{"error": {"code", "message"}}`` instead of FastAPI's ``{"detail": ...}``, so
|
|
57
|
+
the UI can show it. Headers such as ``WWW-Authenticate`` are kept."""
|
|
58
|
+
|
|
59
|
+
def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
|
|
60
|
+
handler = super().get_route_handler()
|
|
61
|
+
|
|
62
|
+
async def route_handler(request: Request) -> Response:
|
|
63
|
+
try:
|
|
64
|
+
return await handler(request)
|
|
65
|
+
except HTTPException as exc:
|
|
66
|
+
extra: dict[str, Any] = {}
|
|
67
|
+
if isinstance(exc, RedlineHTTPError):
|
|
68
|
+
code, message, extra = exc.code, exc.message, exc.extra
|
|
69
|
+
else:
|
|
70
|
+
code = _CODES.get(exc.status_code, "http_error")
|
|
71
|
+
detail = exc.detail
|
|
72
|
+
message = detail if isinstance(detail, str) else str(detail or code)
|
|
73
|
+
return error_response(
|
|
74
|
+
exc.status_code, code, message, dict(exc.headers or {}), extra
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
return route_handler
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def build_router(redline: Any, dependencies: Sequence[Any]) -> APIRouter:
|
|
81
|
+
router = APIRouter(
|
|
82
|
+
dependencies=list(dependencies), include_in_schema=False, route_class=RedlineRoute
|
|
83
|
+
)
|
|
84
|
+
|
|
85
|
+
@router.get("/")
|
|
86
|
+
async def index() -> HTMLResponse:
|
|
87
|
+
return HTMLResponse(ui.index_html(), headers={**_NO_STORE, **_SECURITY})
|
|
88
|
+
|
|
89
|
+
@router.get("/assets/{path:path}")
|
|
90
|
+
async def assets(path: str) -> Response:
|
|
91
|
+
file = ui.asset_path(f"assets/{path}")
|
|
92
|
+
if file is None:
|
|
93
|
+
return error_response(404, "not_found", "No such asset.")
|
|
94
|
+
return FileResponse(
|
|
95
|
+
file, media_type=ui.content_type(file), headers={**_IMMUTABLE, **_SECURITY}
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
@router.get("/api/stream")
|
|
99
|
+
async def live(request: Request) -> Response:
|
|
100
|
+
"""Server-sent events: one ``trace`` event per new trace (``CONTRACT.md`` §12)."""
|
|
101
|
+
try:
|
|
102
|
+
since = stream.parse_since(request.query_params)
|
|
103
|
+
except FilterError as exc:
|
|
104
|
+
return error_response(400, "invalid_filter", str(exc))
|
|
105
|
+
return StreamingResponse(
|
|
106
|
+
stream.async_events(
|
|
107
|
+
redline.api,
|
|
108
|
+
since,
|
|
109
|
+
request.is_disconnected,
|
|
110
|
+
after=stream.parse_after(request.query_params, request.headers),
|
|
111
|
+
),
|
|
112
|
+
media_type=stream.CONTENT_TYPE,
|
|
113
|
+
headers=stream.SSE_HEADERS,
|
|
114
|
+
)
|
|
115
|
+
|
|
116
|
+
@router.api_route(
|
|
117
|
+
"/api/{path:path}",
|
|
118
|
+
methods=["GET", "POST", "DELETE", "PUT", "PATCH"], # the core answers 405 for the last two
|
|
119
|
+
)
|
|
120
|
+
async def api(request: Request, path: str) -> Response:
|
|
121
|
+
redline.loop = asyncio.get_running_loop()
|
|
122
|
+
if path.strip("/") in ("login", "logout"): # the access gate's own endpoints
|
|
123
|
+
body = await request.body() if request.method == "POST" else None
|
|
124
|
+
decision = redline.access.handle(request_info(request, redline.prefix), body)
|
|
125
|
+
if decision is not None:
|
|
126
|
+
return JSONResponse(
|
|
127
|
+
decision.body(),
|
|
128
|
+
status_code=decision.status,
|
|
129
|
+
headers={**_NO_STORE, **_SECURITY, **decision.headers},
|
|
130
|
+
)
|
|
131
|
+
params: dict[str, Any] = {}
|
|
132
|
+
for key, value in request.query_params.multi_items():
|
|
133
|
+
if key in params:
|
|
134
|
+
prev = params[key]
|
|
135
|
+
params[key] = [*prev, value] if isinstance(prev, list) else [prev, value]
|
|
136
|
+
else:
|
|
137
|
+
params[key] = value
|
|
138
|
+
body = await request.body() if request.method == "POST" else None
|
|
139
|
+
# the server's own listening port, never the Host header (CONTRACT.md §18)
|
|
140
|
+
scope = request.scope
|
|
141
|
+
base_url = own_base_url(
|
|
142
|
+
scope.get("scheme"), scope.get("server"), scope.get("root_path", "")
|
|
143
|
+
)
|
|
144
|
+
status, payload = await run_in_threadpool(
|
|
145
|
+
redline.api.dispatch, request.method, f"api/{path}", params, body, base_url=base_url
|
|
146
|
+
)
|
|
147
|
+
if isinstance(payload, RawResponse): # the snapshot page
|
|
148
|
+
return Response(
|
|
149
|
+
payload.body,
|
|
150
|
+
status_code=payload.status,
|
|
151
|
+
media_type=payload.content_type,
|
|
152
|
+
headers={**payload.headers, **_NO_STORE, **_SECURITY},
|
|
153
|
+
)
|
|
154
|
+
return JSONResponse(payload, status_code=status, headers={**_NO_STORE, **_SECURITY})
|
|
155
|
+
|
|
156
|
+
@router.get("/{name}")
|
|
157
|
+
async def top_level(name: str) -> Response:
|
|
158
|
+
file = ui.asset_path(name) # badge.js, favicon.svg etc.
|
|
159
|
+
if file is None:
|
|
160
|
+
return error_response(404, "not_found", "Not found.")
|
|
161
|
+
return FileResponse(
|
|
162
|
+
file, media_type=ui.content_type(file), headers={**_NO_STORE, **_SECURITY}
|
|
163
|
+
)
|
|
164
|
+
|
|
165
|
+
return router
|
|
@@ -0,0 +1,267 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: fastapi-redline
|
|
3
|
+
Version: 0.2.0a1
|
|
4
|
+
Summary: A modern request profiler for FastAPI and SQLAlchemy: span timelines, N+1 detection with fix diffs, one-click EXPLAIN, flamegraphs and a fast web UI.
|
|
5
|
+
Project-URL: Homepage, https://github.com/Pythondeveloper6/redline
|
|
6
|
+
Project-URL: Documentation, https://pythondeveloper6.github.io/redline/fastapi/
|
|
7
|
+
Project-URL: Source, https://github.com/Pythondeveloper6/redline
|
|
8
|
+
Project-URL: Issues, https://github.com/Pythondeveloper6/redline/issues
|
|
9
|
+
Project-URL: Changelog, https://github.com/Pythondeveloper6/redline/blob/main/CHANGELOG.md
|
|
10
|
+
Author-email: Mahmoud Ahmed <pythondeveloper6@gmail.com>
|
|
11
|
+
Maintainer-email: Mahmoud Ahmed <pythondeveloper6@gmail.com>
|
|
12
|
+
License-Expression: MIT
|
|
13
|
+
License-File: LICENSE
|
|
14
|
+
Keywords: explain,fastapi,flamegraph,n+1,performance,profiler,sqlalchemy,starlette
|
|
15
|
+
Classifier: Development Status :: 3 - Alpha
|
|
16
|
+
Classifier: Environment :: Web Environment
|
|
17
|
+
Classifier: Framework :: AsyncIO
|
|
18
|
+
Classifier: Framework :: FastAPI
|
|
19
|
+
Classifier: Intended Audience :: Developers
|
|
20
|
+
Classifier: Operating System :: OS Independent
|
|
21
|
+
Classifier: Programming Language :: Python :: 3
|
|
22
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
23
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
24
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
25
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
26
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
27
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
28
|
+
Classifier: Topic :: Software Development :: Debuggers
|
|
29
|
+
Classifier: Topic :: System :: Monitoring
|
|
30
|
+
Classifier: Typing :: Typed
|
|
31
|
+
Requires-Python: >=3.10
|
|
32
|
+
Requires-Dist: fastapi<1.0,>=0.110
|
|
33
|
+
Requires-Dist: redline-core==0.2.0a1
|
|
34
|
+
Requires-Dist: sqlalchemy[asyncio]<3.0,>=2.0
|
|
35
|
+
Provides-Extra: profile
|
|
36
|
+
Requires-Dist: redline-core[profile]==0.2.0a1; extra == 'profile'
|
|
37
|
+
Description-Content-Type: text/markdown
|
|
38
|
+
|
|
39
|
+
<p align="center">
|
|
40
|
+
<a href="https://pythondeveloper6.github.io/redline/">
|
|
41
|
+
<picture>
|
|
42
|
+
<source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Pythondeveloper6/redline/main/docs/assets/logo-dark.svg">
|
|
43
|
+
<img alt="Redline" src="https://raw.githubusercontent.com/Pythondeveloper6/redline/main/docs/assets/logo-light.svg" height="56">
|
|
44
|
+
</picture>
|
|
45
|
+
</a>
|
|
46
|
+
</p>
|
|
47
|
+
|
|
48
|
+
# fastapi-redline
|
|
49
|
+
|
|
50
|
+
The FastAPI + SQLAlchemy adapter for [Redline](https://github.com/Pythondeveloper6/redline#readme): a request profiler and
|
|
51
|
+
backend analyzer. Every request becomes a trace with a span timeline, the SQL it ran, N+1
|
|
52
|
+
and duplicate-query detection with **concrete fix diffs**, one-click `EXPLAIN`, optional
|
|
53
|
+
flamegraphs, and a fast web UI served from your own app.
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
from fastapi import FastAPI
|
|
57
|
+
from sqlalchemy.ext.asyncio import create_async_engine
|
|
58
|
+
from fastapi_redline import install
|
|
59
|
+
|
|
60
|
+
app = FastAPI()
|
|
61
|
+
engine = create_async_engine("sqlite+aiosqlite:///app.db")
|
|
62
|
+
|
|
63
|
+
# access="local": localhost only (unset, Redline answers 404 outside debug mode)
|
|
64
|
+
install(app, engine=engine, settings={"access": "local"}) # UI at http://localhost:8000/_redline/
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Traces are stored in their own SQLite file (`.redline/redline.db`), never in your database.
|
|
68
|
+
|
|
69
|
+
## Install
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
pip install \
|
|
73
|
+
"fastapi-redline @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/fastapi-redline" \
|
|
74
|
+
"redline-core @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/redline-core"
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Not on PyPI yet: install from GitHub, naming `redline-core` in the same command (the adapter
|
|
78
|
+
pins it exactly). Docs: <https://pythondeveloper6.github.io/redline/>.
|
|
79
|
+
|
|
80
|
+
Add the extra to the core requirement for flamegraphs:
|
|
81
|
+
`"redline-core[profile] @ git+https://github.com/Pythondeveloper6/redline#subdirectory=packages/redline-core"`.
|
|
82
|
+
|
|
83
|
+
Python 3.10+, FastAPI 0.110+, SQLAlchemy 2.x.
|
|
84
|
+
|
|
85
|
+
## `install()`
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
install(
|
|
89
|
+
app,
|
|
90
|
+
engine=None, # Engine | AsyncEngine | [engines] | {"alias": engine}
|
|
91
|
+
settings=None, # dict | redline_core.Settings
|
|
92
|
+
prefix=None, # default: the mount_path setting, else "/_redline"
|
|
93
|
+
dependencies=None, # auth dependencies for the UI + API (see below)
|
|
94
|
+
models=None, # Base / registry for fix suggestions (default: auto-discover)
|
|
95
|
+
store=None, # custom Store (default: SQLite file at storage_path)
|
|
96
|
+
) -> Redline
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
What it does:
|
|
100
|
+
|
|
101
|
+
- configures the recorder and the store, and **flushes and closes the store on shutdown**
|
|
102
|
+
(it wraps your lifespan; an existing `lifespan=` keeps working);
|
|
103
|
+
- adds a pure ASGI middleware (not `BaseHTTPMiddleware`);
|
|
104
|
+
- instruments the engines;
|
|
105
|
+
- mounts the UI and JSON API under `prefix` (ahead of any catch-all route you declared).
|
|
106
|
+
|
|
107
|
+
Call it after your app is built, before it starts. `settings` takes any
|
|
108
|
+
[Redline setting](../redline-core/README.md) with case-insensitive keys:
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
install(app, engine=engine, settings={
|
|
112
|
+
"sample_rate": 0.1, # keep 10% of requests ...
|
|
113
|
+
"always_keep_slower_than_ms": 300, # ... plus every slow one and every error
|
|
114
|
+
"slow_query_ms": 50,
|
|
115
|
+
})
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
### Multiple engines
|
|
119
|
+
|
|
120
|
+
The first engine of a list is the `"default"` db alias; others are named after their
|
|
121
|
+
database file, or pass a dict. The alias is stored on each query so EXPLAIN runs on the right
|
|
122
|
+
engine.
|
|
123
|
+
|
|
124
|
+
```python
|
|
125
|
+
install(app, engine=[async_engine, sync_engine])
|
|
126
|
+
install(app, engine={"main": main_engine, "analytics": analytics_engine})
|
|
127
|
+
redline = install(app)
|
|
128
|
+
redline.add_engine(late_engine) # instrument an engine created later
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### SQLModel
|
|
132
|
+
|
|
133
|
+
Nothing to do: SQLModel tables live in a regular SQLAlchemy registry, which the fix
|
|
134
|
+
suggester discovers (or pass `models=SQLModel`).
|
|
135
|
+
|
|
136
|
+
## What is recorded
|
|
137
|
+
|
|
138
|
+
- **Request / response**: method, path, route template (`/orders/{order_id}`), endpoint
|
|
139
|
+
dotted name, status, headers, query string and body. Secrets are redacted by the core
|
|
140
|
+
(`Authorization`, cookies, `password`/`token`/`card` keys...).
|
|
141
|
+
- **Bodies are never consumed or buffered unboundedly.** The request body is copied as the
|
|
142
|
+
app reads it; response bodies, including streams, are kept only up to `max_body_bytes`.
|
|
143
|
+
- **SQL** through `before/after_cursor_execute`: statement, bound params (redacted),
|
|
144
|
+
duration, rowcount, vendor, executemany, `db_alias`, and the project line that issued the
|
|
145
|
+
query, also through `AsyncSession` (the greenlet boundary is bridged).
|
|
146
|
+
- **Unhandled exceptions** are recorded and re-raised untouched.
|
|
147
|
+
- Spans from `def` endpoints running in Starlette's threadpool attach to the right request
|
|
148
|
+
(context is copied to the worker thread; tested under concurrency).
|
|
149
|
+
- The trace is finished when the last response chunk is sent, so background tasks do not
|
|
150
|
+
inflate latency. Work that starts a bare `threading.Thread` is not attributed to any
|
|
151
|
+
request.
|
|
152
|
+
- Your own spans: `with redline_core.span("pricing.compute"): ...` (also `async with` and
|
|
153
|
+
as a decorator).
|
|
154
|
+
- `X-Redline-Run: <id>;step=<n>` becomes tags (used by the load tester).
|
|
155
|
+
|
|
156
|
+
### Outbound HTTP (httpx)
|
|
157
|
+
|
|
158
|
+
Opt-in, once at startup:
|
|
159
|
+
|
|
160
|
+
```python
|
|
161
|
+
from fastapi_redline import instrument_httpx
|
|
162
|
+
|
|
163
|
+
instrument_httpx() # every httpx.Client / AsyncClient call becomes an http_out span
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
URLs are redacted (`?api_key=...` is masked). Use `uninstrument_httpx()` to undo it.
|
|
167
|
+
|
|
168
|
+
### Profiling
|
|
169
|
+
|
|
170
|
+
Flamegraphs are opt-in per request: add `?_redline=profile` or the header
|
|
171
|
+
`X-Redline-Profile: 1` (needs the `[profile]` extra). They are recorded with pyinstrument in
|
|
172
|
+
async mode, so concurrent requests do not pollute each other.
|
|
173
|
+
|
|
174
|
+
## Fix suggestions
|
|
175
|
+
|
|
176
|
+
For an N+1, `SQLAlchemyFixSuggester` maps the repeated query back to your models and tells
|
|
177
|
+
you how to eager-load it:
|
|
178
|
+
|
|
179
|
+
| Repeated query | Suggestion |
|
|
180
|
+
|---|---|
|
|
181
|
+
| child table filtered by its foreign key | `selectinload(Parent.children)` |
|
|
182
|
+
| parent looked up by primary key, once per row | `joinedload(Child.parent)` |
|
|
183
|
+
| association (secondary) table filtered by the parent | `selectinload(Parent.tags)` |
|
|
184
|
+
|
|
185
|
+
It then walks the call stack to find the `select(Parent)` or `session.query(Parent)` in
|
|
186
|
+
your source and produces a real unified diff:
|
|
187
|
+
|
|
188
|
+
```diff
|
|
189
|
+
- orders = (await session.scalars(select(Order).order_by(Order.id).limit(30))).all()
|
|
190
|
+
+ orders = (await session.scalars(select(Order).order_by(Order.id).limit(30).options(selectinload(Order.items)))).all()
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
plus the `from sqlalchemy.orm import selectinload` line when it is missing. When the
|
|
194
|
+
statement cannot be located (it lives in another module, or is built dynamically) you get
|
|
195
|
+
the one-line code hint with lower confidence instead. Both the lazy-load form
|
|
196
|
+
(`order.items`) and explicit per-row queries are recognised.
|
|
197
|
+
|
|
198
|
+
## Access control
|
|
199
|
+
|
|
200
|
+
The UI exposes your SQL, request bodies and EXPLAIN, so treat it like an admin tool.
|
|
201
|
+
|
|
202
|
+
**Default.** With no `dependencies`, the `access` setting decides (default `local`, served only in debug mode until you set `access`): only loopback clients (127.0.0.0/8, `::1`; unix sockets only with `trust_unix_socket`)
|
|
203
|
+
that address the server by a loopback name (`Host: localhost`, `127.0.0.1`, `[::1]`, any port;
|
|
204
|
+
this blocks DNS rebinding)
|
|
205
|
+
are served and a warning is logged at startup. Refusals, and `HTTPException`s from your own
|
|
206
|
+
dependencies, are JSON `{"error": {"code": "forbidden" | "unauthorized" | ..., "message"}}`.
|
|
207
|
+
Add other host names with the `allowed_hosts` setting. Passing `dependencies=` implies
|
|
208
|
+
`access="framework"`. A loopback peer sending `X-Forwarded-For` without being in
|
|
209
|
+
`trusted_proxies` is refused; behind a reverse proxy use `access="token"` and
|
|
210
|
+
`trusted_proxies`. Tokens, basic auth, `allowed_ips` and `read_only` are described in the
|
|
211
|
+
[access control docs](https://pythondeveloper6.github.io/redline/access-control/).
|
|
212
|
+
|
|
213
|
+
**Your existing auth dependency:**
|
|
214
|
+
|
|
215
|
+
```python
|
|
216
|
+
from fastapi import Depends
|
|
217
|
+
|
|
218
|
+
install(app, engine=engine, dependencies=[Depends(require_admin_user)])
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
**HTTP Basic:**
|
|
222
|
+
|
|
223
|
+
```python
|
|
224
|
+
import secrets
|
|
225
|
+
from fastapi import Depends, HTTPException
|
|
226
|
+
from fastapi.security import HTTPBasic, HTTPBasicCredentials
|
|
227
|
+
|
|
228
|
+
basic = HTTPBasic()
|
|
229
|
+
|
|
230
|
+
def redline_auth(creds: HTTPBasicCredentials = Depends(basic)) -> None:
|
|
231
|
+
ok = secrets.compare_digest(creds.username, "admin") and secrets.compare_digest(
|
|
232
|
+
creds.password, os.environ["REDLINE_PASSWORD"]
|
|
233
|
+
)
|
|
234
|
+
if not ok:
|
|
235
|
+
raise HTTPException(401, headers={"WWW-Authenticate": "Basic"})
|
|
236
|
+
|
|
237
|
+
install(app, engine=engine, dependencies=[Depends(redline_auth)])
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
(`dependencies=[]` is the same as passing none. A dependency that returns `False` is refused with 403; raising `HTTPException` is the normal way.)
|
|
241
|
+
|
|
242
|
+
**CSRF.** The mutating endpoints (`DELETE` traces, `POST explain`) reject browser requests
|
|
243
|
+
whose `Origin` does not match the request host, `Origin: null`, and
|
|
244
|
+
`Sec-Fetch-Site: cross-site`. Browsers always send `Origin` on those methods, so another
|
|
245
|
+
website cannot drive your Redline through a logged-in browser. Non-browser clients (curl,
|
|
246
|
+
scripts) send no `Origin` and are only subject to your auth dependencies.
|
|
247
|
+
|
|
248
|
+
## EXPLAIN
|
|
249
|
+
|
|
250
|
+
`POST /_redline/api/explain` runs `EXPLAIN` for a recorded SELECT on the engine it came
|
|
251
|
+
from (matched by `db_alias`) inside a transaction that is always rolled back (and
|
|
252
|
+
`READ ONLY` on PostgreSQL). The captured SQL is in the driver's paramstyle and goes
|
|
253
|
+
through `exec_driver_sql`. Async engines run on the application's event loop. `EXPLAIN
|
|
254
|
+
ANALYZE` executes the query, so it is off unless `explain_analyze=True`.
|
|
255
|
+
|
|
256
|
+
## Development
|
|
257
|
+
|
|
258
|
+
```bash
|
|
259
|
+
uv sync --all-packages
|
|
260
|
+
cd packages/fastapi-redline && uv run pytest
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
A runnable demo with deliberately bad endpoints lives in [`examples/fastapi`](https://github.com/Pythondeveloper6/redline/blob/main/examples/fastapi).
|
|
264
|
+
|
|
265
|
+
## License
|
|
266
|
+
|
|
267
|
+
MIT
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
fastapi_redline/__init__.py,sha256=0xj6hdidt7az8J1msC-Zm7VT5pIrlMrHXUqbzuqxT-E,997
|
|
2
|
+
fastapi_redline/_httpx.py,sha256=vd2nVdA4K1khx0KWjJC-ojmG8vk_5BTCzJ1YckP_zvk,220
|
|
3
|
+
fastapi_redline/_middleware.py,sha256=kzj_Lluoj51QcqVP3aeSQt9xV1EyVTe5jPseS0B4pww,11065
|
|
4
|
+
fastapi_redline/_security.py,sha256=wyAb8oHQpdDX7s4KvoshW4Qz0CAzbyoBvbykuL2jvdo,8798
|
|
5
|
+
fastapi_redline/_serialize.py,sha256=dR-cqTN1XW-JrQ4Gu3ETx3pj0KXHNmsGHbfuHdhOJ48,3997
|
|
6
|
+
fastapi_redline/_sqlalchemy.py,sha256=zho_YxZqGNZpDChZmnAxb_tIHR56zAHbLj_UlHHAPLo,384
|
|
7
|
+
fastapi_redline/integration.py,sha256=Kbc92cRB8ipLQ9pZMp2oP5GuYUDoe6qq1dSQupwCLXw,8678
|
|
8
|
+
fastapi_redline/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
fastapi_redline/router.py,sha256=Qp7EKm8Tuwd16ZwIgmpIBU_vUfE6SzK-pKw-K_ujYZI,6395
|
|
10
|
+
fastapi_redline/suggest.py,sha256=XNw_skhJ8ww-y080vUhCoEGRG02hvzK1h6DC-9M_MlY,242
|
|
11
|
+
fastapi_redline-0.2.0a1.dist-info/METADATA,sha256=hvvIk5LwbzZCoXHXA9kA8eBkg1OtALi9nouKoujrKzI,11516
|
|
12
|
+
fastapi_redline-0.2.0a1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
13
|
+
fastapi_redline-0.2.0a1.dist-info/licenses/LICENSE,sha256=iNRgkNhv4ywVj_7s8Rd8Vq6wO10lRkZMX9KAsNwivKU,1070
|
|
14
|
+
fastapi_redline-0.2.0a1.dist-info/RECORD,,
|