asgi-profiler 0.1.0__tar.gz

asgi_profiler-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+.ruff_cache/
+.pytest_cache/
+.ty_cache/
+example.db
+profiler.db
+*.db-wal
+*.db-shm
+.coverage
+htmlcov/
+_to_delete/
+REVIEW.md

asgi_profiler-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,83 @@
+# Runs the same checks CI runs, before the commit exists rather than after.
+#
+# Install once per clone:
+#
+#     uv run --all-extras pre-commit install
+#
+# `default_install_hook_types` means that one command wires up both stages:
+# the fast checks on every commit, and the test suite on push.
+#
+# Why the linters are `repo: local` rather than the upstream mirrors:
+# `astral-sh/ruff-pre-commit` pins its own ruff version, so the pinned `rev`
+# here and the version in `uv.lock` drift apart the moment either is bumped --
+# and then a commit passes locally and the identical code fails in CI, which
+# is the one failure mode a pre-commit hook exists to prevent. Going through
+# `uv run` means the hook and CI are running the same build of the same tool,
+# resolved from the same lockfile, always.
+
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  # ------------------------------------------------------- format and lint
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        # Formats rather than checks: the point of the hook is that you never
+        # see the CI formatting failure at all. Also reformats Python inside
+        # fenced blocks in the markdown, which is how README.md broke CI once.
+        entry: uv run --all-extras ruff format
+        language: system
+        types_or: [python, markdown]
+        require_serial: true
+
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --all-extras ruff check --fix
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+
+      # ------------------------------------------------ types and security
+      # Whole-package, so no filenames are passed: `ty` needs the imports to
+      # resolve, and a bandit finding can sit in a file the commit did not
+      # touch. `files:` still limits *when* they fire.
+      - id: ty
+        name: ty check
+        entry: uv run --all-extras ty check src/asgi_profiler
+        language: system
+        pass_filenames: false
+        files: ^src/
+        require_serial: true
+
+      - id: bandit
+        name: bandit
+        # src only: the suite is full of asserts and temp paths, which bandit
+        # flags by design and which say nothing about the shipped package.
+        entry: uv run --all-extras bandit -q -r src/asgi_profiler
+        language: system
+        pass_filenames: false
+        files: ^src/
+        require_serial: true
+
+      - id: uv-lock
+        name: uv lock is in sync with pyproject.toml
+        # The check CI makes with `uv sync --locked`. Catching it here saves a
+        # round trip, because a stale lock fails every job at once.
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+        files: ^(pyproject\.toml|uv\.lock)$
+
+  # ------------------------------------------------------- on push: tests
+  - repo: local
+    hooks:
+      - id: pytest
+        name: pytest
+        # Push, not commit: the suite takes seconds rather than milliseconds,
+        # and a hook slow enough to be worth skipping gets skipped.
+        entry: uv run --all-extras pytest -q
+        language: system
+        pass_filenames: false
+        always_run: true
+        stages: [pre-push]

asgi_profiler-0.1.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+<!-- markdownlint-disable MD024 -->
+
+# Changelog
+
+All notable changes to `asgi-profiler` are documented here. The format is
+based on [Keep a Changelog](https://keepachangelog.com/) and this project
+follows [Semantic Versioning](https://semver.org/).
+
+## [0.1.0] - 11.09.2026
+
+First release. Request and SQL profiling for **ASGI** applications —
+**Starlette**, **FastAPI** — with **SQLAlchemy** and **SQLModel**.
+`install(app)` is the whole integration: no settings module, no database
+table, no migration.
+
+### Added
+
+- `install(app)` — adds a pure-ASGI middleware and mounts the viewer. Returns a
+  `Profiler` handle with `slowest()`, `search()`, `summary()`, `statements()`
+  and `close()`.
+- SQL capture through SQLAlchemy's `before_cursor_execute`,
+  `after_cursor_execute` and `handle_error` events, attached to the `Engine`
+  class — so every engine in the process is covered, SQLModel needs no special
+  support, and async engines work unchanged.
+- Per-query application stacks, walked across the greenlet boundary that
+  SQLAlchemy's async support puts between the query and your code.
+- Statements that raise are recorded with their error and filterable.
+- Route-pattern grouping: `/users/1` and `/users/2` aggregate as
+  `/users/{user_id}`, recovered by replaying the router where the framework
+  does not expose it, and correct under mounts and typed converters.
+- **Requests** page — filterable and paginated, with `N+1 ×n` and `SQL error`
+  badges.
+- **Request detail** page — repeated statements collapse into one row with a
+  `×N` badge, the spread of their timings, a sample of the parameters, and one
+  copy of the stack that issued them.
+- **Summary** page — grouped by route, with p50/p95/p99 rather than an average.
+- **Statements** page — every statement aggregated across all requests.
+- JSON for every page (`/requests.json`, `/request/<id>.json`,
+  `/summary.json`, `/statements.json`), so a test can fail a build when an
+  endpoint regresses to an N+1.
+- `X-Profiler-Id` response header, linking a slow response to its trace.
+- `MemoryStorage` (default) and `SQLiteStorage`, the latter shared across
+  `uvicorn` workers and written from a background thread so no `fsync` or lock
+  wait lands on the event loop.
+- `Storage` protocol plus a `BaseStorage` that supplies searching, paging,
+  summarising and statement aggregation, so a custom backend needs five
+  methods.
+- `python -m asgi_profiler profiler.db` — browse a capture file offline,
+  read-only, with no application.
+- `authorize=` hook, sync or async. `POST /clear` rejects cross-site requests.
+- `py.typed`, checked in CI with both `mypy` and `ty`, on Python 3.10–3.13.
+
+### Known limitations
+
+- No Python-side profiling yet: when an endpoint is slow and the SQL is not,
+  "time in Python" is a single number with nothing behind it.
+- Request and response bodies are never recorded.
+- WebSockets are not recorded.
+- The `Engine`-class listeners are process-wide, so the profiler cannot be
+  scoped to one engine and the most recent `install()` decides
+  `capture_stacks`.
+- `max_requests` bounds the number of requests kept, not their total size.

asgi_profiler-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,63 @@
+# Contributing
+
+```console
+uv sync --all-extras
+uv run pre-commit install
+```
+
+That is the whole setup. `pre-commit install` wires up both stages at once:
+formatting, linting, types, security and the lockfile check on every commit,
+and the test suite on push.
+
+`--all-extras` matters: without it FastAPI is missing and the tests covering
+FastAPI route handling skip in silence.
+
+To run things by hand, or to see what the hooks will do before committing:
+
+```console
+uv run pre-commit run --all-files              # everything the commit hook runs
+uv run pre-commit run --all-files --hook-stage pre-push   # the above, plus pytest
+```
+
+The individual commands, if you want one of them on its own:
+
+```console
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+uv run ty check src/asgi_profiler
+uv run bandit -q -r src/asgi_profiler
+```
+
+Two things worth knowing about the hooks:
+
+- The linters are `repo: local` and go through `uv run`, so they are the
+  versions in `uv.lock` — the same ones CI uses. The upstream `ruff-pre-commit`
+  mirror pins its own version, which drifts from the lockfile and lets a commit
+  pass locally and fail in CI on identical code.
+- `ruff format` also formats the Python inside fenced blocks in the markdown
+  files, so a README snippet can fail the format check. The hook fixes it in
+  place rather than just reporting it.
+
+## Ground rules
+
+- **Every bug fix gets a regression test that fails without the fix.**
+  `tests/test_regressions.py` is organised that way; keep it that way.
+- **Behaviour that differs between storage backends is a bug.**
+  `tests/test_storage_and_viewer.py` parametrises the same assertions over
+  `MemoryStorage` and `SQLiteStorage`. A new backend should join that fixture.
+- **Comments explain *why*, not *what*.** The non-obvious choices in this
+  codebase — pure ASGI over `BaseHTTPMiddleware`, a mutable contextvar, class-
+  level engine listeners, walking the stack by hand — are all load-bearing, and
+  each is commented where it lives. If you change one of them, change the
+  comment in the same commit.
+- Keep the profiler's own overhead in mind: anything added to the per-query
+  path is paid for on every statement your users run.
+
+## Releasing
+
+1. `uv version --bump patch` (or `minor` / `major`). Nothing to mirror:
+   `__version__` is read from the installed distribution.
+2. Date the new section in `CHANGELOG.md`.
+3. Tag `X.Y.Z` (no `v` prefix) and push. `release.yml` re-runs the suite on every supported
+   Python, builds with `uv build --no-sources`, verifies the tag matches the
+   packaged version, and publishes with `uv publish` over Trusted Publishing.

asgi_profiler-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Miradil Zeynalli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

asgi_profiler-0.1.0/PKG-INFO

@@ -0,0 +1,436 @@
+Metadata-Version: 2.5
+Name: asgi-profiler
+Version: 0.1.0
+Summary: Request and SQL profiling for ASGI apps: Starlette, FastAPI, SQLAlchemy
+Project-URL: Source, https://github.com/mmzeynalli/asgi-profiler
+Project-URL: Issues, https://github.com/mmzeynalli/asgi-profiler/issues
+Project-URL: Changelog, https://github.com/mmzeynalli/asgi-profiler/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,fastapi,n+1,profiler,profiling,silk,sql,sqlalchemy,sqlmodel,starlette
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Requires-Python: >=3.10
+Requires-Dist: jinja2>=3.0
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: starlette>=0.35
+Provides-Extra: dev
+Requires-Dist: bandit; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: ty; extra == 'dev'
+Requires-Dist: uvicorn; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: aiosqlite; extra == 'test'
+Requires-Dist: anyio; extra == 'test'
+Requires-Dist: fastapi; extra == 'test'
+Requires-Dist: httpx; extra == 'test'
+Requires-Dist: httpx2; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: sqlmodel; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img alt="asgi-profiler" src="assets/logo.svg" width="380">
+  </picture>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/asgi-profiler/"><img alt="PyPI package" src="https://img.shields.io/pypi/v/asgi-profiler?color=%2334D058&label=pypi%20package"></a>
+  <a href="https://pypi.org/project/asgi-profiler/"><img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/asgi-profiler.svg?color=%2334D058"></a>
+  <a href="https://pepy.tech/project/asgi-profiler"><img alt="Downloads" src="https://static.pepy.tech/badge/asgi-profiler"></a>
+  <a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/mmzeynalli/asgi-profiler"><img alt="Coverage" src="https://coverage-badge.samuelcolvin.workers.dev/mmzeynalli/asgi-profiler.svg"></a>
+  <br>
+  <a href="https://github.com/mmzeynalli/asgi-profiler/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/mmzeynalli/asgi-profiler/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://www.gnu.org/licenses/mit.en.html"><img alt="License" src="https://img.shields.io/badge/license-MIT-16A34A"></a>
+  <a href="https://github.com/astral-sh/ruff"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
+  <a href="https://github.com/mmzeynalli/asgi-profiler"><img alt="Typed" src="https://img.shields.io/badge/typed-py.typed-0F766E"></a>
+</p>
+<!-- markdownlint-enable MD033 -->
+
+---
+
+Request and SQL profiling for **ASGI** applications — **Starlette** and
+**FastAPI**, with **SQLAlchemy** and **SQLModel**. It records every request your
+application handles along with the SQL each one ran, and serves a browsable UI
+that tells you which endpoint is slow, whether it is the database, and which
+line of your code issued the query.
+
+```python
+from fastapi import FastAPI
+from asgi_profiler import install
+
+app = FastAPI()
+install(app)  # viewer at /profiler
+```
+
+That is the whole integration. No settings module, no database table, no
+migration.
+
+## Table of Contents
+
+- [Key features](#key-features)
+- [Installation](#installation)
+- [Usage](#usage)
+- [What it shows](#what-it-shows)
+- [JSON](#json)
+- [Configuration](#configuration)
+- [Storage](#storage)
+- [Security](#security)
+- [How it works](#how-it-works)
+- [Limits](#limits)
+- [Prior art](#prior-art)
+- [Development](#development)
+- [Licence](#licence)
+
+---
+
+## Key features
+
+- **One line to install.** `install(app)` adds the middleware and mounts the
+  viewer. You never hand the profiler an engine.
+- **N+1 detection that names the line.** Repeated statements collapse into a
+  single row with a `×N` badge and the stack that issued them — a 500-row N+1
+  is one line to read, not 500 to scroll.
+- **Grouped by route, not by path.** `/users/1` and `/users/2` aggregate as
+  `/users/{user_id}`, with p50/p95/p99 rather than an average.
+- **Cross-request statement view.** Which SQL costs you application-wide, not
+  just on the endpoint you happen to be looking at.
+- **JSON for every page**, so a test can fail a build when an endpoint
+  regresses.
+- **Works with async engines**, sync engines, several engines at once, and
+  SQLModel — with no configuration for any of them.
+- **Two storage backends**, one of them shared across `uvicorn` workers.
+- Fully typed and `py.typed`, checked in CI with `ty`, and scanned with `bandit`.
+
+| | Supported |
+|---|---|
+| Starlette | ✅ |
+| FastAPI | ✅ |
+| SQLAlchemy 2.x (sync) | ✅ |
+| SQLAlchemy 2.x (async) | ✅ |
+| SQLModel | ✅ |
+| Python 3.10 – 3.13 | ✅ |
+| Litestar | planned |
+
+## Installation
+
+```console
+pip install asgi-profiler
+```
+
+Dependencies are `starlette`, `sqlalchemy` and `jinja2` — all of which you
+already have.
+
+## Usage
+
+```python
+from fastapi import FastAPI
+from asgi_profiler import install
+
+app = FastAPI()
+install(app)
+```
+
+Make some requests, then open `/profiler`.
+
+`install()` returns a handle if you want the data programmatically:
+
+```python
+profiler = install(app)
+...
+for profile in profiler.slowest(5):
+    print(profile.route, profile.query_count, profile.duplicate_count)
+
+for statement in profiler.statements(10):
+    print(f"{statement.total_ms:.0f}ms  x{statement.count}  {statement.sql[:60]}")
+```
+
+> [!Note]
+> `profiler.profiles` returns everything, which on a large `SQLiteStorage`
+> means deserialising every statement of every request. Prefer `slowest()`,
+> `search()`, `summary()` and `statements()`, which the backend can answer
+> without hydrating the history. Call `profiler.close()` on shutdown to
+> release a file-backed store.
+
+## What it shows
+
+**Requests** — every request, newest first: method, path, status, wall time,
+time in SQL, query count. Rows that repeat a statement carry an `N+1 ×n`
+badge; rows with a statement that raised carry a `SQL error` badge. Filter by
+path substring, method, status class, route or a minimum duration; sort by most
+recent, slowest, most queries or most SQL time; or narrow to N+1s or failures
+only. Paginated.
+
+**Request detail** — status, total time, time in SQL, time in Python, query
+count, duplicate count and error count, then the statements it ran. Repeated
+statements collapse into one row carrying a `×N` badge, the total/average/max
+time across those runs, a sample of the parameters, and *one* copy of the stack
+that issued them all. Slow and failed statements are marked, and
+request/response headers are shown with `authorization`, `cookie` and friends
+redacted.
+
+**Summary** — every request grouped by method and route pattern, so `/users/1`
+and `/users/2` are one row rather than two: calls, p50/p95/p99, max, total
+time, average queries, total duplicates and total SQL errors, heaviest first.
+Percentiles rather than the average, which one outlier ruins.
+
+**Statements** — every statement grouped by its SQL, across *all* requests:
+runs, how many requests ran it, runs-per-request, total, average and max time,
+and how many routes it appears on. The per-request view tells you why *this*
+endpoint is slow; this tells you what is costing you application-wide — the
+query that runs three times on eleven endpoints is invisible in the former and
+obvious here.
+
+Every response also carries an `X-Profiler-Id` header, so you can go straight
+from a slow response to its trace at `/profiler/request/<id>`.
+
+## JSON
+
+Every page has a JSON twin — `/profiler/requests.json` (honours the same
+filters), `/profiler/request/<id>.json`, `/profiler/summary.json`,
+`/profiler/statements.json`. Which makes the profiler scriptable, and lets a
+test fail a build when an endpoint regresses:
+
+```python
+def test_the_dashboard_has_no_n_plus_one(client):
+    client.get("/dashboard")
+    trace = client.get("/profiler/requests.json").json()["requests"][0]
+    assert trace["duplicate_count"] == 0, "N+1 reintroduced"
+    assert trace["query_count"] <= 5
+```
+
+## Configuration
+
+```python
+from asgi_profiler import install
+
+install(
+    app,
+    mount_path="/_perf",  # anywhere; every link is relative to the mount
+    max_requests=1000,
+    exclude_paths=["/healthz"],  # matched on segment boundaries
+    capture_stacks=True,  # the per-query stacks; costs a little per query
+    stack_depth=8,
+    slow_request_ms=500,
+    slow_query_ms=50,
+    capture_headers=True,
+    response_header="x-profiler-id",  # None to add nothing
+    page_size=50,
+    statement_limit=100,  # rows on the Statements page
+    authorize=lambda request: request.headers.get("x-key") == "...",
+)
+```
+
+## Storage
+
+The default is an in-memory ring buffer: zero configuration, lost on restart,
+and **per process** — under `uvicorn --workers 4` the viewer shows you one
+worker's quarter of the traffic. If that matters, use SQLite:
+
+```python
+from asgi_profiler import SQLiteStorage, install
+
+install(app, storage=SQLiteStorage("profiler.db", max_requests=5000))
+```
+
+History then survives restarts and every worker writes to the same file.
+
+Writes go through a background thread, because `add()` is called while the
+event loop is running: a synchronous insert there means an `fsync`, and with
+several workers on one WAL file a lock wait that `sqlite3` implements as a
+blocking sleep. Measured at up to 230 ms of stall in a single `add()` before
+this changed; it is now ~1 µs to enqueue. Reads flush first, so you never see a
+stale page. Pass `background=False` for synchronous writes.
+
+Paging and ordering are pushed down into SQL and stay flat as history grows.
+The `?q=` path filter is a substring match, which no index can serve, so it
+scans — about 8 ms over 20,000 rows. Fine for a development tool; it is not a
+log search engine.
+
+Any object satisfying the `Storage` protocol works. Subclass `BaseStorage` and
+you only need five methods — searching, paging, summarising and statement
+aggregation are supplied, and you can override them where your backend can do
+better:
+
+```python
+from asgi_profiler import BaseStorage
+
+
+class RedisStorage(BaseStorage):
+    def add(self, profile): ...
+    def get(self, profile_id): ...
+    def list(self, *, limit=None, offset=0): ...
+    def count(self): ...
+    def clear(self): ...
+```
+
+### Reading a capture without the app
+
+```console
+python -m asgi_profiler profiler.db      # viewer on :8080
+```
+
+Capture in staging, read the file on your laptop. No application required, and
+the file is opened read-only.
+
+## Security
+
+> [!Caution]
+> **The viewer has no authentication of its own.** It exposes SQL, parameters
+> and request headers. Either keep it off outside development, or pass
+> `authorize=`.
+
+```python
+install(app, authorize=lambda request: request.user.is_staff)
+
+
+# async is fine too -- and any realistic guard is async
+async def only_staff(request):
+    return await is_staff(request.user)
+
+
+install(app, authorize=only_staff)
+```
+
+A common pattern is to install it conditionally:
+
+```python
+if settings.DEBUG:
+    install(app)
+```
+
+`POST /clear` only accepts `Sec-Fetch-Site: same-origin` (or a same-origin
+`Origin`), so another site — including a sibling subdomain — cannot make your
+browser wipe your history. That is not authentication, though, and it is not a
+substitute for `authorize=`.
+
+## How it works
+
+**Requests** are captured by a pure-ASGI middleware. Pure ASGI rather than
+`BaseHTTPMiddleware` on purpose: the latter runs the downstream app in a
+separate task, which breaks the contextvar that query attribution depends on.
+
+**Queries** are captured with SQLAlchemy's own `before_cursor_execute`,
+`after_cursor_execute` and `handle_error` events, attached to the `Engine`
+**class**. That is why you never hand the profiler an engine, and why SQLModel
+needs no special support: `sqlmodel.create_engine` returns a SQLAlchemy
+`Engine` and `sqlmodel.Session` subclasses `sqlalchemy.orm.Session`, so the
+same events fire. Async engines are covered too — `AsyncEngine` drives a sync
+`Engine` underneath, and that is where the events live.
+
+**Attribution** uses a contextvar holding a mutable list. It has to be mutable:
+SQLAlchemy's sync work often runs in a worker thread, and anyio copies the
+context into that thread, so appends made there must land in an object the
+request task already holds. The test suite fires concurrent requests with
+different query counts and asserts none of them bleed.
+
+**Route patterns** come from `scope["route"]` where the framework sets one
+(FastAPI does, and that path is free). Plain Starlette sets no `route` key at
+all, so the router is replayed once after the response to find which route
+matched — exact where reconstructing from `path_params` is not, since a
+`{uid:int}` matching `007` and a value that collides with a literal segment
+both defeat string substitution. Patterns are returned absolute, so a sub-app
+mounted at two prefixes does not collapse into one summary row.
+
+**Stacks** are walked outward from the query and stop as soon as enough
+application frames are found, crossing the greenlet boundary that SQLAlchemy's
+async support puts between the query and your code.
+`traceback.extract_stack()` would unwind the whole stack and read source lines
+for every frame before discarding almost all of it, which on a realistic
+100-frame async stack costs ~20× more per query.
+
+**URLs** in the UI are all relative to the mount prefix, taken from
+`scope["root_path"]` when the server sets one — which is also what accounts for
+a proxy prefix — and otherwise from the `prefix` passed to `build_viewer`.
+
+## Limits
+
+- **Overhead is real.** Two event callbacks and a `perf_counter` pair per
+  query, plus a stack capture if enabled — around 20 µs per query in situ,
+  which on a 20-query endpoint is a ~70% increase in wall time. On plain
+  Starlette, a *parameterised* route also costs one replayed routing pass per
+  request to recover its pattern — about 11 µs at 50 routes, 42 µs at 200.
+  FastAPI does not pay this. Development tool, not production telemetry.
+- **No Python-side profiling yet.** When an endpoint is slow and the SQL is
+  not, "time in Python" is a single number with nothing behind it. A cProfile
+  panel is the next thing to build.
+- **No request or response bodies.** They carry credentials and can be large.
+- **WebSockets are not recorded.** Only HTTP requests are.
+- **Global hooks.** Listeners are on the `Engine` class, so every engine in the
+  process is captured. That is deliberate — it is what makes app-wide capture
+  work — but it means you cannot scope the profiler to one engine, and
+  `capture_stacks` / `stack_depth` are process-wide (the most recent
+  `install()` wins).
+- **Unmatched requests and raw ASGI mounts group by path.** A 404 has no route
+  to name, and a mount to a bare ASGI app (StaticFiles, say) exposes none.
+  `exclude_paths` if that is noisy.
+- **`max_requests` bounds requests, not bytes.** Statements over 4000
+  characters are truncated, but a request running thousands of queries still
+  retains all of them.
+
+## Prior art
+
+There is no *actively maintained* equivalent of
+[django-silk](https://github.com/jazzband/django-silk) for this stack, but
+there is prior art worth knowing about:
+
+| Project | Notes |
+|---|---|
+| [fastapi-debug-toolbar](https://github.com/mongkok/fastapi-debug-toolbar) | A django-debug-toolbar port with a SQLAlchemy panel. FastAPI only; last release May 2024. |
+| [fastapi-sql-profiler](https://pypi.org/project/fastapi-sql-profiler/) | SQL profiling for FastAPI. |
+
+This project differs in being Starlette-level rather than FastAPI-only, in not
+injecting a toolbar into your responses, and in offering a cross-request
+summary aggregated by route alongside per-query application stacks.
+
+## Development
+
+```console
+uv sync --all-extras
+uv run pre-commit install
+uv run pytest
+```
+
+`pre-commit install` is the whole check setup: `ruff format`, `ruff check`,
+`ty`, `bandit` and a lockfile check run on every commit, and the suite runs on
+push. To run them without committing:
+
+```console
+uv run pre-commit run --all-files
+```
+
+Building and publishing go through uv too:
+
+```console
+uv build --no-sources
+```
+
+Releases are cut by pushing a bare version tag (`0.1.0`); CI builds and
+publishes with
+`uv publish` over PyPI Trusted Publishing, so no token is stored anywhere.
+
+The suite covers recording, SQL capture, N+1 detection and collapsing, failed
+statements, stack capture and ordering across the greenlet boundary, header
+redaction, history bounds, every viewer page parsed for well-formed HTML,
+filters, pagination, the JSON endpoints, custom mount paths, proxy root paths,
+the authorize hook (sync and async), CSRF on clear, route-pattern grouping
+under mounts and typed converters, async engines, multiple engines in one
+process, concurrent request attribution, both storage backends asserted against
+the same expectations, a custom storage backend, and queries issued outside any
+request.
+
+## Licence
+
+MIT.