Skip to main content

pagebar

A tiny prod-safe perf footer for ASGI apps. One line at the bottom of every page, click to expand. No SQL text, no env vars, no stack traces — nothing that could leak.

v2026.6.19 · 22ms · 4 SQL · GET /editeurs

pagebar's footer pill

Click it to expand the full panel:

The expanded pagebar panel

The text is selectable, and the copy icon in the pill puts every field on the clipboard. Browsers only expose the clipboard on https and localhost, so the icon is hidden elsewhere.

Install

pip install pagebar              # core only
pip install pagebar[sqlalchemy]  # with SQL query counter
pip install pagebar[flask]       # Flask (WSGI) integration

Use

Starlette / FastAPI

from pagebar import PagebarMiddleware, pagebar_html
from starlette.applications import Starlette
from starlette.middleware import Middleware

app = Starlette(
    middleware=[Middleware(PagebarMiddleware, package="my-app")],
    routes=[...],
)

Litestar (and other mw_cls(app)-style frameworks)

Litestar instantiates middleware as cls(app) with no further kwargs, so config has to be baked in. Use PagebarMiddleware.bound(...):

from litestar import Litestar
from pagebar import PagebarMiddleware

app = Litestar(
    middleware=[
        PagebarMiddleware.bound(package="my-app", unsafe=False),
    ],
    route_handlers=[...],
)

.bound(**kwargs) returns a thin subclass with the kwargs baked into __init__. Same fields as the regular constructor.

Flask (WSGI)

Flask isn't ASGI, so there's no middleware — the pagebar[flask] extra ships a small extension that wires the same data collection into Flask's request lifecycle:

from flask import Flask
from pagebar.flask import Pagebar

app = Flask(__name__)
Pagebar(app, package="my-app", unsafe=app.debug)

Same knobs as PagebarMiddleware. pagebar_html is registered as a Jinja global, so the template usage below works unchanged. enabled/unsafe callables receive the Flask request (the ASGI versions get the connection scope).

Template

In your base template, anywhere inside <body>:

{{ pagebar_html() | safe }}
</body>

That's it. One name for the middleware, one for the helper.

What's on screen

Field Source
Version importlib.metadata.version(package) — or explicit version=
Time time.perf_counter() delta
SQL SQLAlchemy cursor-execute listeners (if installed): count, total time, share of Time
Other Time minus SQL time; flagged ⚠ from 500ms, in the pill too
Request method + path
Peak memory resource.getrusage().ru_maxrss — highest RSS so far in MiB, not current
Uptime time.monotonic() since worker import
Threads threading.active_count()
GC gc.get_count() — gen0/gen1/gen2 pending
Python sys.version_info
PID os.getpid()

No SQL text. No params. No env. No traces. That's the whole surface.

Other is what makes a slow page legible without SQL to blame: Time: 2.31s, SQL: 16 queries, 7ms (<1%), Other: 2.30s ⚠ says at a glance to stop reading the SQL report.

SQL time stops when execute returns, so time spent fetching rows counts under Other. That's usually small with drivers that load the whole result during execute, such as psycopg's default cursor. SQLite and server-side cursors do the work during the fetch, so a slow query there can show almost no SQL time.

Knobs

PagebarMiddleware(
    app,
    package="my-app",  # distribution name (PyPI / pyproject.toml)
    version="",  # escape hatch: bypass importlib.metadata lookup
    enabled=True,  # bool or callable(scope) -> bool
    unsafe=False,  # bool or callable(scope) -> bool — see below
    query_budget=20,  # >0 → log a WARNING when SQL count exceeds this
    time_budget=1.0,  # >0 → log a WARNING when a request takes longer (seconds)
)

Unsafe mode

In dev, you usually want to see the SQL text. Flip unsafe=True and the panel gains a SQL summary with a SQL details button. That opens a full-screen modal with two sections: a grouped N+1 report (each unique statement with its repeat count and total time, repeats flagged in red — the panel also shows how many queries were redundant), and the full list of every query in order with bound parameters and per-statement timing. The modal text is selectable, and a Copy report button puts a self-contained N+1 summary on the clipboard — request line, totals, and each unique statement with its call count — ready to paste into a bug report:

pagebar SQL report — GET /widgets
21 queries, 2 unique, 19 redundant (possible N+1)

20×  0.0ms  SELECT name FROM widget WHERE id = ?
 1×  0.1ms  SELECT id FROM widget

The expanded panel in unsafe mode, with the SQL summary and details button

The unsafe-mode SQL modal: grouped N+1 report above a collapsible full-query list

Unsafe mode also samples stacks while the request runs, every 10ms, so a slow page names the code responsible. When Other is flagged, the panel shows the most frequent stacks, keeping the innermost frame and the application frames above it, with Jinja frames on their template line. Loop blocked appears when the event loop couldn't run anything else, the difference between one slow request and a frozen server:

Time: 2.15s
SQL: 16 queries, 7ms (<1%)
Other: 2.14s ⚠
Loop blocked: 2.14s ⚠

97% of samples in obstore/store.py:281 head
  ← front_app/storage.py:217 _exists
  ← front_app/storage.py:121 logo_url
  ← templates/pages/solutions/detail.html:55 block_content

The copy icon includes these stacks, and time_budget adds them to its log line. The sampling thread only exists while a sampled request is in flight. Concurrent requests see each other's stacks. If no code was running, the panel says the time went to an await.

A red UNSAFE badge in the pill makes the mode obvious.

The pill in unsafe mode, with a red UNSAFE badge

import os

PagebarMiddleware(app, package="my-app", unsafe=bool(os.getenv("DEBUG")))
# or framework-driven
PagebarMiddleware(app, package="my-app", unsafe=app.debug)

unsafe defaults to False and only takes its value from constructor wiring — no URL parameter, no header, no cookie. The host's deploy config is the authority.

enabled lets you hide the bar from JSON endpoints, healthchecks, or admin routes:

def show(scope):
    return not scope["path"].startswith(("/api/", "/health"))


Middleware(PagebarMiddleware, package="my-app", enabled=show)

Bots are skipped automatically (User-Agent matching bot|crawler|spider). On a skipped request, pagebar_html() returns an empty string, so the template needs no condition. It does the same if the middleware isn't installed.

CSP

pagebar_html() accepts a nonce keyword that's applied to the inline <style> and <script>:

{{ pagebar_html(nonce=csp_nonce) | safe }}

Otherwise the host needs 'unsafe-inline' for both directives. No external assets, no third-party requests.

Why not the Django/Flask/Litestar debug toolbars?

They reveal SQL text, environment, settings, request bodies, stack traces — fine in dev, unacceptable in production. pagebar surfaces a fixed, public-safe set of fields. The shape is the security model.

Non-goals

No panels system, no plugins, no per-framework adapters, no APM, no time series, no SQL EXPLAIN, no full profiler. One ASGI middleware, one helper function and an optional Flask extension.

License

MIT.

Metadata

Release files for pagebar 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pagebar 0.2.0
File Size Uploaded Provenance Actions
pagebar-0.2.0.tar.gz 17.9 kB Without provenance Details for pagebar-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pagebar 0.2.0
File Interpreter ABI Platform Actions
pagebar-0.2.0-py3-none-any.whl Python 3 none any Details for pagebar-0.2.0-py3-none-any.whl

Total release size: 37.3 kB

Release files / pagebar-0.2.0.tar.gz

Download URL pagebar-0.2.0.tar.gz
Size 17.9 kB
Tags Source
SHA-256 checksum
How to use checksums
9c87d09cabc84b7869239c5eb187e30c595f25bfa87578b0daa54a3b2b3ab6ab
BLAKE2b-256 checksum
How to use checksums
89d868c4a4940b75ebbee71fa17119d42ebd80a8c11e0e96788248cb95fa7b01
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / pagebar-0.2.0-py3-none-any.whl

Download URL pagebar-0.2.0-py3-none-any.whl
Size 19.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f83475301382d0797cdde1b10ca219f34ab3b1a3324c9a016cc7883a732cb303
BLAKE2b-256 checksum
How to use checksums
27e54190768fb556e8c1b43c80e8e6cced3a4956e9abba58f1684e700ed68028
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.4 {"installer":{"name":"uv","version":"0.13.4","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for pagebar 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page