Configuration

Every kwarg connect() takes, every environment variable it reads, and the brokers it supports.

connect()

celeryradar_sdk.connect(
    api_key,
    app_name,
    endpoint='https://api.celeryradar.com',
    broker_url=None,
    capture_args=True,
    capture_exceptions=True,
    worker_name=None,
)

api_key str, required

Your environment's ingest key, from the settings page. Sent as a Bearer token on every request.

Each environment (production, staging, dev, etc.) has its own API key. Read the right key per deploy target from an environment variable — don't hardcode. See Environments for how plan tiers gate the number of environments and what happens on downgrade.

app_name str, required

Identifier for this Celery app within your account. If you run multiple Celery apps under one API key (even on separate Redis brokers), give each a distinct app_name (e.g. 'orders', 'workers', 'api'). Used to scope the broker-side leader-election lock and to keep colliding queue names (two apps that both have a queue called celery) separate in the dashboard.

Renaming an existing app: tasks, workers, beat schedules, and the alert rules tied to them are not scoped by app_name and keep working unchanged. Queue depth is the only thing scoped. Old QueueDepth rows tagged with the previous name go quiet immediately and age out under retention; new samples accumulate under the new name from the next poll. The one footgun is queue_depth_threshold alert rules: each one carries the app_name you picked when you created it, so after a rename they query the old name and silently never fire again. Edit the affected rules and update the app_name field, or recreate them.

endpoint str, default https://api.celeryradar.com

Override only if you're testing against a self-run instance or a private CeleryRadar deployment. The trailing /ingest/ is appended automatically.

broker_url str, default None

Explicit broker URL for the queue depth poller. Defaults to app.conf.broker_url from the active Celery app, which is what you want unless your monitoring credentials are scoped differently from your worker credentials (e.g. a read-replica with a separate user).

capture_args bool, default True

When true, task arguments are captured and shipped with each event so they appear in the task detail page. Set to False if your tasks accept PII or secrets as arguments. With it off, you still get task name, state, runtime, retry count, and exception info; just not the arg values.

Args/kwargs are capped at 4 KB combined; oversized payloads are replaced with a truncation marker. Non-JSON-serializable values are coerced via repr().

capture_exceptions bool, default True

When true, the exception repr() and traceback string are shipped with task-failed and task-retried events and rendered on the task detail page. Set to False if your exception messages might contain user input (e.g. ValueError: invalid email [email protected]), DB errors with interpolated SQL parameters, or if stack frames disclosing your file paths are sensitive. With it off, you still see that a task failed (state, retry count, runtime), just no exception or traceback details.

This is a coarse all-or-nothing toggle. There's no separate switch for "keep traceback, drop message" — if you need that, open an issue on the SDK repo.

worker_name str, default None

Override the hostname reported to ingest. Without this, the SDK uses socket.gethostname(), which in a Kubernetes pod returns an ephemeral pod name that rotates on every restart and accumulates ghost workers in your dashboard. Set this to a stable per-deployment name in your manifest.

The CELERYRADAR_WORKER_NAME environment variable takes precedence over this kwarg, so deployment manifests can override the value without code changes.

Environment variables

CELERYRADAR_WORKER_NAME optional

Stable name for this worker. Wins over the worker_name= kwarg and over socket.gethostname(). Set this in your k8s manifest, ECS task definition, or systemd unit.

Empty values fall through (so an unset env var doesn't override a configured kwarg).

That's the full list. The SDK doesn't read any other env vars. There's no global config file, no .celeryradar.toml, no auto-discovery beyond what's described above.

Where to call connect()

Anywhere your Celery app is initialized. The most common places:

Standalone Celery app: right after app = Celery(...).
Django + Celery: in config/celery.py after app.config_from_object(...).
Celery beat as a separate process: call connect() in the beat entrypoint too. Beat schedule monitoring relies on the beat_init signal firing in the beat process.

The SDK hooks Celery signals (task_prerun, task_postrun, task_failure, task_retry, heartbeat_sent, beat_init, before_task_publish, worker_process_init), so it must be imported and connected before Celery starts dispatching those signals (i.e. at module load time, not lazily inside a task).

Broker support

Broker	Tasks & workers	Beat	Queue depth
Redis (lists)	✓	✓	✓
RabbitMQ	✓	✓	not yet
SQS	✓	✓	not yet
Redis Cluster / Sentinel / Streams	✓	✓	not yet

Task lifecycle, worker heartbeats, and beat schedule monitoring are all driven by Celery signals, so they work with any broker Celery itself supports. Queue depth polling is the only piece that needs to talk to your broker directly. Today that means a standard Redis list-mode broker (redis:// or rediss://).

If you're on an unsupported broker, queue depth charts will silently stay empty. Everything else still works.

How the SDK works

The async architecture, retry queue, fork safety, and payload handling. The parts you should understand before running this in production.

Reference

What gets monitored

Tasks, workers, beat schedules, queue depth: the four signal types and how each is detected.