Installation

Tracepanel for Python is the tracepanel package. It records the traces of your Python app and sends them to the agent.

tracepanel, tracepanel-agent and django-tracepanel come out together, at the same version. The current one is 0.2.0. pip install tracepanel installs the agent of the same version. See the changelog.

Install the packageCopy Anchor Link

pip install tracepanel

For Django, you can install django-tracepanel instead. It has no code of its own and installs the same package as pip install "tracepanel[django]".

pip install django-tracepanel

The package also installs tracepanel-agent, the program that stores the traces and serves the console. You don't install or start it yourself. See How it works. The agent comes as a wheel for the platforms in Supported versions. On any other platform, tracepanel installs without it.

Add it to your appCopy Anchor Link

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

python manage.py runserver

Open a page of your app and click the badge in the corner to open the panel. The console is at /__tracepanel__/.

When it turns onCopy Anchor Link

Tracepanel records only in development. It turns on in one of these cases:

• Django runs with DEBUG = True.
• FastAPI or Starlette runs with debug=True, or Flask runs in debug mode.
• The command runs under tracepanel run.
• The TRACEPANEL_ENABLED=1 variable is set.

Otherwise Tracepanel does nothing. It adds no middleware and patches nothing. Falcon has no debug mode, so tracepanel.falcon.install(app) turns on only under tracepanel run, with TRACEPANEL_ENABLED=1 or with install(app, enabled=True).

Run without changing your codeCopy Anchor Link

tracepanel run starts a command with Tracepanel on. You don't change the project:

tracepanel run python manage.py runserver   # Django
tracepanel run uvicorn app.main:app         # FastAPI, Starlette
tracepanel run flask --app app run          # Flask
tracepanel run gunicorn app:app             # Falcon
tracepanel run celery -A app worker         # a Celery worker

tracepanel run sets up each framework as your code imports it. For Django, it adds tracepanel.django to INSTALLED_APPS while Django reads the settings. For FastAPI, Starlette, Flask and Falcon, it installs Tracepanel on each app as the app is created. Tracepanel is on even when DEBUG is off, so you can look at production-like settings locally.

A worker or a script needs no framework. Under tracepanel run, every library integration turns on as your code imports its library: the task queues, SQLAlchemy, the database drivers, the HTTP clients, Redis, MongoDB, Strawberry, OpenTelemetry and logging. See Integrations.

Workers and commandsCopy Anchor Link

A task or a management command has no page for the panel. Each task run and each 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 agent serves the console at that link even when no web server is running. The agent picks a free port when it starts, so the port changes from run to run. The trace's page in the console lists its issues.

Supported versionsCopy Anchor Link

Tracepanel for Python supports Python 3.11 to 3.15. See Integrations for the oldest version of each framework and library it supports.

The agent ships for Linux, macOS and Windows:

• Linux on glibc: x86_64, arm64 (glibc 2.28 or newer), armv7, i686, ppc64le, s390x and riscv64 (glibc 2.31 or newer).
• Linux on musl, such as Alpine: x86_64, arm64, armv7, armv6 and i686.
• macOS: Apple silicon and Intel.
• Windows: x86_64, x86 and arm64.

On another platform, pip install tracepanel installs the package without the agent. Build the agent from its source package, which needs Rust, with pip install tracepanel-agent. Or point the TRACEPANEL_AGENT_BIN variable at an agent you built.