Tracepanel

Settings

Configure Tracepanel in a Django project with the TRACEPANEL dict, and the settings a Django project changes most.

Tracepanel works with no settings. To change one, add the TRACEPANEL dict to your settings:

# settings.py
TRACEPANEL = {
    "slow_sql_ms": 200,
    "ignore_paths": ["/health*", "/static/*"],
}

Four Django settings feed Tracepanel's:

  • DEBUG turns it on.
  • INSTALLED_APPS must hold tracepanel.django for it to turn on.
  • BASE_DIR is the project's directory. Stack paths are relative to it, and the store is in it.
  • INTERNAL_IPS lists the addresses besides this machine that may switch the user. See Safety.

Where settings come from

You can set each setting in four places. A later place wins over an earlier one:

  1. tracepanel.toml, or [tool.tracepanel] in pyproject.toml.
  2. The TRACEPANEL dict in Django's settings.
  3. tracepanel.core.conf.configure() in code.
  4. TRACEPANEL_<NAME> environment variables, such as TRACEPANEL_SLOW_SQL_MS=200. tracepanel run --set slow_sql_ms=200 sets the same variable for one command.

Tracepanel reports an unknown name or a wrong type as an error that names where the value came from.

tracepanel config prints every setting, its value and the place that set it:

tracepanel config

It doesn't read Django's settings. It shows the values from the defaults, tracepanel.toml or pyproject.toml, and the environment variables, but not the TRACEPANEL dict, DEBUG or BASE_DIR. So enabled shows false in a Django project even when Tracepanel is on. Run it from the project's directory.

The settings a Django project changes

SettingDefaultWhat it does
enabledDEBUGWhether Tracepanel records anything. TRACEPANEL_ENABLED, which tracepanel run sets, wins over DEBUG.
slow_sql_ms100Queries slower than this are reported as slow SQL. So are MongoDB queries and other datastore calls, as slow calls.
slow_http_ms500Outgoing HTTP calls slower than this are reported as slow.
n_plus_one_threshold3How many similar queries from one place make an N+1.
n_plus_one_min_ms5Repeated Redis commands and cache calls are reported only when they cost this much together.
long_transaction_ms500Outer atomic() blocks longer than this are reported.
ignore_paths/health*, /static/*, /media/*, /favicon.icoRequests whose path matches are not traced.
ignore_commandsservers, shells, the test runner and workersManagement commands that are not traced.
ignore_tasksnoneTasks that are not traced, such as celery.backend_cleanup.
ignore_loggersnoneLoggers whose records are left out, with their children.
user_switchTrueLet the panel show the site as another user. See Safety.
widgetTrueAdd the badge and the panel to HTML pages.
prefix/__tracepanel__/The URL of the console.
terminal_summaryTruePrint a line in the terminal after each task run and management command.
capture_sql_paramsTrueKeep query parameters and MongoDB values, so the console can run EXPLAIN.
capture_localsTrueKeep the local variables of your frames in errors, masked.
capture_mail_bodyTrueKeep the text and HTML of sent emails.
capture_task_argsTrueKeep task arguments and results, masked.
max_traces2000How many traces the store keeps. Older ones are deleted.
agentautoWhere traces go. Set an address when the app runs in a container and the agent outside it.

Each library integration has an *_enabled setting, such as drf_enabled. See What it records.

Two thresholds are fixed. A task that waited in its queue for a second or more is a queue wait. A query without a LIMIT that returned 1,000 rows or more is a large result.

The full list, the same for every framework, is in Configuration.

What it records

The parts of Django that Tracepanel records with no setup, the Django libraries it traces, and the issues it finds in them.

Safety

Why Tracepanel stays off outside development, what it keeps about your data, who can read it, and when the panel can switch the user.

On this page

Where settings come fromThe settings a Django project changes