# Configuration (/docs/python/configuration)

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

## Where settings come from [#where-settings-come-from]

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

1. `tracepanel.toml`, or `[tool.tracepanel]` in `pyproject.toml`.
2. 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()`.
3. `tracepanel.core.conf.configure()` in code.
4. `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.

<Tabs items={["pyproject.toml", "Django", "Flask", "FastAPI", "Variable"]}>
  <Tab value="pyproject.toml">

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

  </Tab>
  <Tab value="Django">

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

In Django, `DEBUG` sets `enabled` and `BASE_DIR` sets `root`. See
[Django settings](/docs/django/settings).

  </Tab>
  <Tab value="Flask">

```python
from flask import Flask

import tracepanel.flask

app = Flask(__name__)
app.config["TRACEPANEL"] = {"slow_sql_ms": 50}
tracepanel.flask.install(app)
```

  </Tab>
  <Tab value="FastAPI">

```python
from fastapi import FastAPI

import tracepanel.fastapi

app = FastAPI(debug=True)
tracepanel.fastapi.install(app, slow_sql_ms=50)
```

  </Tab>
  <Tab value="Variable">

```bash
TRACEPANEL_SLOW_SQL_MS=50 python manage.py runserver
```

A variable takes `1`, `true`, `yes` or `on` for true, and `0`, `false`, `no`
or `off` for false. A list takes comma-separated values, such as
`TRACEPANEL_IGNORE_PATHS=/health*,/static/*`.

  </Tab>
</Tabs>

`tracepanel run --set name=value` sets the `TRACEPANEL_<NAME>` variable for
one run. See [Command line](/docs/python/cli).

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 [#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:

```text
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 [#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 [#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 [#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](/docs/python/integrations) for what each one records.