Skip to main content

xtr-web-profiler

A development toolbar on every page, and a profile of every request.

python 3.14+ typed license MIT

Why?

"What did that request actually do?" is the question asked most while building a web application, and print statements answer it one piece at a time. In development, this package answers it for every request at once: a toolbar at the foot of each HTML page shows the status, the time, the memory, the log, the events and the route, and one click opens the request's full profile — kept for two days and searchable.

  • 🧭 A toolbar on every page. Drawn into each HTML response as it streams out; nothing to add to a template.
  • ⏱️ A timeline. Every event listener, the application's own handling and the whole request on one axis, filterable by duration and by kind.
  • 📜 The request's log. Every record it made — and only its own, however many requests the process serves at once.
  • 💥 The exception, with its frames. Source around each line, local variables, the chain of causes; a link opens the line in your editor.
  • 🔁 Background requests too. The toolbar lists the fetch and XMLHttpRequest calls the page makes, each linked to its own profile.
  • 🧩 Panels from any library. A data collector and a template are a new panel; the profiler does not need to know it exists.

Install

uv run xtr-recipes recipes:add --dev xtr-web-profiler

Requires Python 3.14.4+. It installs as a development dependency: production does not install it, and the recipe lists the bundle for the dev environment only.

Quick start

With xtr-http-kernel already serving the application through setup(app, kernel), adding the package is the whole of it. Start the application in dev, open any HTML page, and the toolbar is at its foot:

$ curl -si localhost:8000/books | grep -i debug
x-debug-token: 3f9a1c
x-debug-token-link: http://localhost:8000/_profiler/3f9a1c

A response that is not a page — JSON from an API — carries the same two headers: follow X-Debug-Token-Link to its profile, or open /_profiler/latest.

What a profile shows

Panel Shows
Request the method, URI, query, parsed body, path parameters, cookies, headers and state of the request; the status and headers of the response; a curl command replaying it. Credentials — Authorization, Cookie, Set-Cookie, and every field named like a password, a secret or a token — are kept as ******
Time the whole request's duration and a timeline of every timed event: the request's section, the application's own handling (controller), each event listener
Memory the peak memory of the process serving the request
AJAX the background requests the page made, listed in its toolbar
Exception what handling raised: class, message, chain of causes, and each frame with its source and local variables
Logs every record the request logged, by level, with its context — when xtr-logging is active. Context entries named like credentials are kept as ****** too
Events the listeners called, how often and for how long, those not called, and the events nobody listened to
Routing the route that answered — name, path template, methods, endpoint, parameters — a redirect's target, and how every route of the application matched the request
Config the Python version, the environment, the active bundles and every xtr package installed

The profiles themselves are collected by xtr-http-kernel; this package shows them.

The toolbar

The toolbar is drawn into a response only when all of these hold: the toolbar is on, the response names a profile in X-Debug-Token, it is no redirect, its content type is HTML, it is no attachment, its body is not compressed, and the request was not a background one — X-Requested-With: XMLHttpRequest, or a fetch the browser marks as not loading a document. It goes in just before the closing </body>, found even when a streamed body splits the tag across two chunks, and Content-Length is dropped since the body grew. A page without </body> goes out as it was.

What goes into the page is small: a placeholder and a script. The script fetches the toolbar from /_wdt/<token> — retrying a moment later when the profile has not been written yet, since it is written once the response has left — and remembers whether you minimised it.

A compressed body cannot be drawn into, and a browser always accepts one. So a request that may get the toolbar — one accepting HTML, or anything, that is not a background request — reaches the application without its Accept-Encoding: an application compressing its responses, with the framework's GZipMiddleware say, leaves its pages uncompressed in development, and its other responses compressed.

Background requests

The page's fetch and XMLHttpRequest calls are recorded as they go, with their status, their duration and the profile named by their response, and listed in the toolbar. Calls to the profiler's own paths are left out — excluded_ajax_paths says which. With ajax_replace, a background request whose response names a profile reloads the toolbar with that profile — for a page that changes what it shows without loading another.

Redirects

With intercept_redirects, a redirect answering a page is replaced by a page saying where it leads, toolbar included, so the request that redirected — a form post, a sign-in — can be read before following it.

Content security policy

The toolbar is an inline script and an inline style. A page sending a policy gets the toolbar's nonces added to every script and style directive of it, so the toolbar runs and the page's own rules stay as they were; a page without a policy is left alone. The profiler's own pages are sent with no policy at all.

A frame of an exception links to the line that ran. By default the link opens the profiler's own source view, which shows only files under the project directory and never a hidden one. Point it at your editor instead with file_link_format, {file} and {line} standing for them:

Editor file_link_format
PyCharm "pycharm://open?file={file}&line={line}"
VS Code "vscode://file/{file}:{line}"
Cursor "cursor://file/{file}:{line}"

Writing a panel

A panel is a data collector — registered by any bundle, see xtr-http-kernel — and a template naming up to four blocks:

  • toolbar — the item in the toolbar: call toolbar_item(name, icon, text, link, status) with the icon and value shown and the text of its popover;
  • menu — the entry in the profile page's menu;
  • panel — the panel itself;
  • head — anything the panel needs in the page's head.

The template is a file of the collector's own package, under templates/, named "@<import package>/<path>"; the package needs no template engine of its own:

{# src/xtr_orm/templates/collector/orm.html.j2 #}
{% block toolbar %}
  {% from "@xtr_web_profiler/profiler/toolbar_item.html.j2" import toolbar_item %}
  {% set icon %}<span class="xtr-toolbar-value">{{ collector.data.count }} queries</span>{% endset %}
  {% set text %}<b>Time</b> {{ collector.data.duration_ms | format_ms }}{% endset %}
  {{ toolbar_item(collector.name, icon, text, link=panel_url(collector.name)) }}
{% endblock %}
{% block menu %}<span class="xtr-label">Database</span>{% endblock %}
{% block panel %}
  {% for query in collector.data.queries %}<pre>{{ query.sql }}</pre>{% endfor %}
{% endblock %}

Every block sees collector — collector.name, and collector.data, what the collector kept — profile, token, url(route_name, **parameters), panel_url(panel), open_file_url(file, line), and the CSP nonces csp_script_nonce and csp_style_nonce for an inline script or style. Filters: profiler_dump shows a value kept through clone_var as a browsable tree; format_bytes, format_ms, format_time and file_link(file, line). A block naming anything else fails, rather than rendering empty.

Use in an application

Everything adding this package to an application on xtr-dependency-injection takes — and, read backwards, what removing it undoes.

  • Install — uv run xtr-recipes recipes:add --dev xtr-web-profiler: a development dependency, never installed in production. xtr-http-kernel comes with it; install xtr-logging beside it for the log panel. The timeline needs nothing more: xtr-stopwatch comes with the http kernel.
  • Recipe — recipes:add does the Activate and Configure steps below: it lists WebProfilerBundle for dev and writes <app>/config/routes/dev/web_profiler.py. There is no environment or ignore line to write; it prints the setup(app, kernel) step, which a recipe cannot make for you.
  • Activate — WebProfilerBundle: {"dev": True} in BUNDLES in <app>/config/bundles.py, imported from xtr_web_profiler.bundle, and setup(app, kernel) where the application is built, as the http kernel requires.
  • Brings along — the http kernel's bundle, required outright, and with it the event dispatcher's. Listing this bundle turns the http kernel's profiler on in the same environment.
  • Configure — <app>/config/routes/dev/web_profiler.py, which the recipe writes, serves the toolbar under /_wdt and the pages under /_profiler; it sits in the dev folder, so nothing of the profiler is routed elsewhere, and deleting it takes the pages down. The bundle's own configuration needs nothing; a change goes in <app>/config/packages/dev/web_profiler.py — see Configure.
  • Environment — nothing.
  • Ignore — nothing: the profiles are kept under the kernel's cache directory.
  • Remove — uv run xtr-recipes recipes:remove xtr-web-profiler drops the BUNDLES entry and deletes <app>/config/routes/dev/web_profiler.py, unless you edited it, in which case it is moved aside.
  • Check — debug:bundles shows web_profiler as listed and active in dev; any HTML page shows the toolbar; GET /_profiler/latest shows the last request's profile.

Configure

WebProfilerConfig is a frozen dataclass buildable with no arguments:

Field Default What it sets
toolbar True draw the toolbar into HTML pages
ajax_replace False reload the toolbar with the profile a background request's response names
intercept_redirects False show a redirect answering a page as a page of its own
excluded_ajax_paths "^/(_wdt|_profiler)" a regular expression; background requests to a matching path are not listed
file_link_format None how a file and line open in an editor — see Editor links

The constructor refuses an excluded_ajax_paths that is no regular expression, and a file_link_format that does not name {file}, with InvalidArgumentError — also a ValueError.

What is profiled — every request, only those asking with a parameter, only failures — is the http kernel's profiler configuration.

Kernel / bundle

# app/config/bundles.py
from xtr_web_profiler.bundle import WebProfilerBundle

BUNDLES = {..., WebProfilerBundle: {"dev": True}}
# app/config/packages/dev/web_profiler.py
from xtr_dependency_injection import configure

from xtr_web_profiler.bundle import WebProfilerConfig


@configure
def web_profiler() -> WebProfilerConfig:
    return WebProfilerConfig(
        intercept_redirects=True,
        file_link_format="pycharm://open?file={file}&line={line}",
    )

The bundle requires the http kernel's bundle and turns its profiler on. It registers the controller answering the pages, the template environment, the content security policy handler and — when the toolbar or redirect interception is on — the toolbar middleware, tagged http_kernel.middleware at priority 1024 (WEB_DEBUG_TOOLBAR_PRIORITY): outside the request lifecycle, whose default is 0, so it sees the profile's token on the response. An application raising HttpKernelConfig.middleware_priority above it keeps the toolbar off its pages. It contributes the route resources web_profiler_wdt and web_profiler. Turned off again through the http kernel's configuration, the profiler records nothing and every page answers 404. The zero-config path builds and boots with nothing configured and touches no disk until a request is profiled.

Security

Never list this bundle outside development. A profile holds every request's headers, cookies, parameters and state; anybody who can reach /_profiler can read them. The recipe lists it for dev only and writes its routes into the dev folder, so in any other environment the pages do not exist, and the bundle warns at build if it finds itself in prod. The token naming a profile is short and not a secret: keeping the pages out of reach is what keeps the profiles private.

Errors

Everything this library raises derives from WebProfilerError.

Error Raised when
InvalidArgumentError a WebProfilerConfig field holds a value the toolbar would misread; also a ValueError
TemplateNotFoundError a data collector's tag names a template that does not exist; also a LookupError

Layout

xtr_web_profiler/
├── web_debug_toolbar_middleware.py  draws the toolbar into the pages, links every profile
├── controller/                      the pages: toolbar, profile, search, source view
├── routing/                         the route resources web_profiler_wdt and web_profiler
├── profiler/                        which panels a profile has, and rendering their blocks
├── templating/                      the template environment, its loader and its filters
├── csp/                             the toolbar's nonces under a page's policy
├── templates/                       the pages, the toolbar and the core panels
├── recipe/                          what recipes:add applies
├── exception/                       WebProfilerError, the root of everything this library raises
└── bundle/                          WebProfilerBundle and WebProfilerConfig

Development

Developed in the python-xtr monorepo, under packages/xtr-web-profiler; run the commands below from there.

uv sync
uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest

License

MIT — see LICENSE.

Metadata

Release files for xtr-web-profiler 7.1.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 xtr-web-profiler 7.1.0
File Size Uploaded Provenance Actions
xtr_web_profiler-7.1.0.tar.gz 67.4 kB With provenance Details for xtr_web_profiler-7.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for xtr-web-profiler 7.1.0
File Interpreter ABI Platform Actions
xtr_web_profiler-7.1.0-py3-none-any.whl Python 3 none any Details for xtr_web_profiler-7.1.0-py3-none-any.whl

Total release size: 152.2 kB

Release files / xtr_web_profiler-7.1.0.tar.gz

Download URL xtr_web_profiler-7.1.0.tar.gz
Size 67.4 kB
Tags Source
SHA-256 checksum
How to use checksums
1117d4251d33a979acde9f1bf3fd9d361e3780dcb5d384a659a5bdcaaf68762e
BLAKE2b-256 checksum
How to use checksums
da69253abae61f2d8fd2b8718136db4b832e14f8c0458edaaae48c667c39d265
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / xtr_web_profiler-7.1.0-py3-none-any.whl

Download URL xtr_web_profiler-7.1.0-py3-none-any.whl
Size 84.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
da3df8002467f7c066ff89d932686209f053e3263ac4ae019a2331f18c88992f
BLAKE2b-256 checksum
How to use checksums
32190b553672cba1d8e3a462ce81df9000b35e16c9297c7782d5f62ee50fd64e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for xtr-web-profiler 7.1.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for xtr_web_profiler-7.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

7.1.0 This release

2 release files Full provenance

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