Installation

Tracepanel supports Django 5.2, 6.0 and 6.1 on Python 3.11 and newer. Django 6.x needs Python 3.12 or newer, and Python 3.15 works with Django 6.1 only.

Install the packageCopy Anchor Link

pip install django-tracepanel

django-tracepanel has no code of its own. It installs the same package as pip install "tracepanel[django]", with the agent that stores the traces and serves the console. See How it works.

django-tracepanel, tracepanel and tracepanel-agent share one version, 0.2.0 now. pip install django-tracepanel installs the matching ones.

The agent comes as a wheel for Linux, macOS and Windows on the common processors. On another platform, tracepanel installs without it and keeps no traces until you point it at an agent elsewhere with the agent setting. See Configuration.

Upgrading from an earlier versionCopy Anchor Link

An upgrade from 0.1 keeps the traces in .tracepanel/. The 0.1.0 agent started a new store there, so the traces of an earlier version aren't carried over.

Add the appCopy Anchor Link

# settings.py
INSTALLED_APPS += ["tracepanel.django"]

You don't add middleware or include URLs. The app puts its middleware first in MIDDLEWARE, so it measures the whole request, and serves /__tracepanel__/ itself.

Start the serverCopy Anchor Link

Tracepanel is on when DEBUG = True. Start the server as usual:

python manage.py runserver

The first line in the terminal shows what Tracepanel turned on, such as this line in a project with Celery on Redis and Django REST framework:

tracepanel ▸ on (DEBUG) · Django · logging, Database drivers, Redis, Celery, Django Tasks, DRF → console at /__tracepanel__/

Open any page, and a badge appears in the bottom right corner. Click it to open the panel. The console is at /__tracepanel__/.

An ASGI server, such as Uvicorn, Daphne or Granian, works the same way. So do async views.

Without changing the settingsCopy Anchor Link

tracepanel run starts a command with Tracepanel on, and you leave the project as it is:

tracepanel run python manage.py runserver

It adds tracepanel.django to INSTALLED_APPS while Django reads the settings, unless the app is there already. It turns Tracepanel on even when DEBUG is off, so you can look at production-like settings locally.

Workers and commandsCopy Anchor Link

A task worker or a management command has no page for the panel. Start the worker as usual. With tracepanel.django in INSTALLED_APPS and DEBUG on, each task run is a trace:

celery -A config worker

To trace a worker without changing the settings, or with DEBUG off, start it with tracepanel run:

tracepanel run celery -A config worker

Each task run and each management command ends with a line in the terminal and a link to its trace:

tracepanel ▸ task newsletter.tasks.send_digest · success · 230 ms · 14 queries → http://127.0.0.1:52811/#/t/01M4…

The link goes to the console that the agent serves, so it works even when no web server is running. The agent picks a free port each time it starts. It stops after 30 minutes unused, and the next trace starts it again.

The dev server, shells, the test runner and task workers are left out as commands of their own. See ignore_commands in Settings.

A frontend on ViteCopy Anchor Link

A single-page app on Vite's dev server, with Django as its API, gets the panel from Tracepanel's Vite plugin. Install @tracepanel/js in the frontend and name Django's console:

// vite.config.ts
import { tracepanel } from "@tracepanel/js/vite";

export default {
  plugins: [tracepanel({ console: "http://localhost:8000/__tracepanel__/" })],
};

The plugin serves Django's console on the frontend's origin, so the panel and EXPLAIN work on the app's pages. It also records the pages in the browser, and Django's console passes their traces on to the agent. See Pages in the browser.