Configuration

Where the Python SDK reads its settings from, which source wins, and every setting with its default.

The Python SDK works with no settings. Every setting has a default, and you change only the ones you need.

Where settings come from

Tracepanel reads settings from these places. A later place wins over an earlier one:

tracepanel.toml, or [tool.tracepanel] in pyproject.toml.
The framework's settings. In Django, that is the TRACEPANEL dict in settings. In Flask, it is app.config["TRACEPANEL"] and the keyword arguments of install(). In FastAPI, Starlette, Falcon and plain ASGI or WSGI apps, it is the keyword arguments of install().
tracepanel.core.conf.configure() in code.
TRACEPANEL_<NAME> environment variables.

Tracepanel looks for tracepanel.toml and pyproject.toml from the project's directory upward. It stops at the first tracepanel.toml, or at the first pyproject.toml, with or without a [tool.tracepanel] section.

# pyproject.toml
[tool.tracepanel]
slow_sql_ms = 50
n_plus_one_threshold = 5
ignore_paths = ["/health*", "/static/*"]

tracepanel run --set name=value sets the TRACEPANEL_<NAME> variable for one run. See Command line.

Tracepanel checks every value against its setting's type. An unknown name or a wrong type raises an error, and the error names the place the value came from.

Check the settings in effect

tracepanel config prints every setting, its value and the place that set it. Then it prints each integration and its state:

slow_sql_ms           200     pyproject.toml [tool.tracepanel]
capture_locals        false   env TRACEPANEL_CAPTURE_LOCALS
...

integrations
  logging           on
  Database drivers  on
  HTTP clients      on
  Redis             off: redis_enabled
  MongoDB           off: not installed
  Celery            on
  DRF               on (Django apps only)

tracepanel config runs outside your app, so it reads the files, the variables and nothing else. It doesn't read Django's settings: the TRACEPANEL dict, DEBUG and BASE_DIR don't show in its output. Nor does it see the keyword arguments of install() or configure() in your code.

Settings

Setting	Default	What it does
`enabled`	`false`	Whether Tracepanel records anything. The framework decides by default: `DEBUG` in Django, debug mode in FastAPI, Starlette, Flask and plain ASGI or WSGI apps. Falcon stays off. `TRACEPANEL_ENABLED`, which `tracepanel run` sets, wins over it.
`root`	the current directory	The project's directory. Stack paths are relative to it, and the store lives in it. Django sets it from `BASE_DIR`.
`service`	the name of `root`	This project's name on the service map.
`widget`	`true`	Adds the panel's script to HTML responses.
`prefix`	`/__tracepanel__/`	The URL prefix of the console, the panel's script and the JSON API.
`dir`	`.tracepanel`	The project's store directory, relative to `root`.
`agent`	`auto`	Where traces go. `auto` sends them to the project's agent and starts it on demand. An address such as `tcp:host.docker.internal:7701` sends them to an agent elsewhere. `off` keeps no traces.
`console_url`	`http://127.0.0.1:8765/`	The console of an agent set by address in `agent`. Terminal lines link here when the project has no agent of its own.
`terminal_summary`	`true`	Prints a line in the terminal after each task run and management command, with a link to its trace.
`max_traces`	`2000`	The number of traces the agent keeps. It deletes older ones.
`n_plus_one_threshold`	`3`	The number of similar queries with different parameters that Tracepanel reports as an N+1. The same goes for MongoDB commands, Redis commands and cache calls.
`n_plus_one_min_ms`	`5`	Tracepanel reports repeated Redis commands and cache calls only when they take this long together, in milliseconds. An in-memory store answers in a fraction of a millisecond.
`slow_sql_ms`	`100`	Tracepanel reports queries slower than this, in milliseconds, as slow SQL. A MongoDB command slower than this is a slow call, with the index it needs.
`slow_http_ms`	`500`	Tracepanel reports outgoing HTTP calls slower than this, in milliseconds, as slow.
`long_transaction_ms`	`500`	Tracepanel reports outer transactions longer than this, in milliseconds. They hold their locks until `COMMIT`.
`capture_locals`	`true`	Keeps the local variables of your project's frames in errors, masked.
`capture_mail_body`	`true`	Keeps the text and HTML of sent emails.
`capture_sql_params`	`true`	Keeps SQL parameter values, so the console can run `EXPLAIN`. Also keeps the values of MongoDB commands.
`user_switch`	`true`	Lets the panel log in as another user, from this machine only.
`capture_task_args`	`true`	Keeps task arguments and results, masked.
`ignore_paths`	`/health`, `/static/`, `/media/*`, `/favicon.ico`	Glob patterns on the request path. Tracepanel doesn't trace matching requests.
`ignore_tasks`	none	Glob patterns on the task name, such as `celery.backend_cleanup`. Tracepanel doesn't trace matching tasks.
`ignore_loggers`	none	Loggers whose records Tracepanel leaves out, with their children. Tracepanel always leaves out its own logs and SQL echo.
`ignore_commands`	servers, shells and workers	Management commands that Tracepanel doesn't trace. The defaults are `runserver`, `runserver_plus`, `shell`, `shell_plus`, `dbshell`, `test`, `testserver`, `db_worker`, `rqworker`, `rqscheduler`, `rundramatiq` and `runworker`. A worker's tasks still become traces of their own.

Fixed thresholds

The agent finds two more issues with limits that you can't change from the Python SDK:

Limit	Value	Issue
`queue_wait_ms`	1 s	`queue-wait`: a task waited longer than this in its queue before a worker took it.
`large_result_rows`	1000 rows	`large-result`: a `SELECT` with no `LIMIT` returned this many rows or more.

Integrations

Each integration patches its library when your app first imports it. Tracepanel doesn't load a library your app never imports. Set an integration's setting to false to leave the library unpatched. Tracepanel reads these settings at startup. All of them default to true.

Setting	Integration
`celery_enabled`	Celery
`channels_enabled`	Django Channels
`dbapi_enabled`	Database drivers used without an ORM
`django_tasks_enabled`	Django Tasks
`dramatiq_enabled`	Dramatiq
`drf_enabled`	Django REST framework
`http_clients_enabled`	Outgoing HTTP calls
`logging_enabled`	Log records from `logging`
`mongodb_enabled`	MongoDB
`ninja_enabled`	Django Ninja
`otel_enabled`	OpenTelemetry
`redis_enabled`	Redis
`rq_enabled`	RQ
`sqlalchemy_enabled`	SQLAlchemy
`strawberry_enabled`	Strawberry

See Integrations for what each one records.

Configuration

Where settings come fromCopy Anchor Link

Check the settings in effectCopy Anchor Link

SettingsCopy Anchor Link

Fixed thresholdsCopy Anchor Link

IntegrationsCopy Anchor Link

On this page

Where settings come from

Check the settings in effect

Settings

Fixed thresholds

Integrations