Configuration

Most package settings are prefixed with CELERY_OUTBOX_. Metrics integration also reads MONITORING_* settings.

Required Settings

Setting	Type	Description
CELERY_OUTBOX_APP	str	Dotted path to your Celery app instance. Example: 'myproject.celery_app.app'. Invalid values fail python manage.py check and runtime startup.

django-celery-outbox also registers Django system checks for database support, applied outbox migrations, and CELERY_OUTBOX_EXCLUDE_TASKS validation.

The database checks (celery_outbox.E001, E005, E006) only run against selected databases: use python manage.py check --database <alias> (with the outbox alias) to verify SKIP LOCKED support and the outbox schema. On Django 6.1+, python manage.py check --tag database without --database selects every configured database, so these checks run there too; on Django < 6.1 that command selects no database and skips them. Commands whose system checks receive no selected databases (a plain python manage.py check, makemigrations, runserver) do not access the database through these checks, so a plain check no longer gates deployments on the outbox schema. migrate runs E001 and skips E005/E006.

Package Settings

Setting	Type	Default	Description
CELERY_OUTBOX_EXCLUDE_TASKS	set[str] \| frozenset[str] \| list[str] \| tuple[str, ...]	set()	Task names to bypass the outbox (sent directly to broker). Invalid values fail in python manage.py check and at runtime.
CELERY_OUTBOX_STRUCTLOG_ENABLED	bool	True	Enable structlog context propagation
CELERY_OUTBOX_STRUCTLOG_CONTEXT_KEYS	list[str] \| None	None	structlog keys to capture. None captures all keys
CELERY_OUTBOX_LOG_EXCEPTION_TRACEBACK	bool	True	Include full traceback in exception logs
CELERY_OUTBOX_PII_REDACTOR	str \| callable	None	Callable (or dotted path to one) that stores redacted inspection copies of task args/kwargs and redacts nested serialized signatures for admin/model inspection
CELERY_OUTBOX_DLQ_RETENTION	dict[str, str] \| None	None	Optional default retention policy for dead-letter purge. Supported keys: older_than_dead, older_than_created, task_name.
CELERY_OUTBOX_STALE_TIMEOUT_SECONDS	int	300	Shared stale-row recovery window used by relay defaults, admin live-backlog summaries, and celery_outbox_stats.

Redaction Notes

• The redactor callable must accept (task_name, args, kwargs).
• Top-level redaction affects the stored redacted_args and redacted_kwargs inspection fields only; the relay still publishes the original payload.
• Nested signatures inside serialized options (link, link_error, chain, chord) are redacted only for inspection surfaces such as Django admin and model properties.

Relay Command Options

python manage.py celery_outbox_relay [OPTIONS]

Option	Default	Description
--batch-size	100	Messages per batch
--idle-time	1.0	Seconds to sleep when queue is empty
--backoff-time	120	Base seconds for exponential backoff
--max-retries	5	Retries before dead letter
--stale-timeout-seconds	CELERY_OUTBOX_STALE_TIMEOUT_SECONDS or 300	Seconds before in-flight rows are considered stale and reclaimable
--send-timeout	10.0	Timeout passed to Celery.send_task() during broker publish
--shutdown-timeout	30.0	Drain window for starting additional sends after SIGTERM/SIGINT
--broker-outage-cooldown	30.0	Process-local breaker cooldown before the next batch attempt
--max-backoff	3600.0	Upper bound for normal message retry delay
--liveness-file	None	File to touch after each batch (for k8s probes)

Metrics Settings

Setting	Type	Default	Description
MONITORING_METRICS_ENABLED	bool	True	Enable or disable all StatsD metric emission
MONITORING_STATSD_HOST	str	'localhost'	StatsD server host
MONITORING_STATSD_PORT	int	9125	StatsD server port
MONITORING_STATSD_PREFIX	str	'celery_outbox'	Metric name prefix
MONITORING_STATSD_TAGS	dict	{}	Default tags for all metrics
CELERY_OUTBOX_DISABLE_TASK_NAME_TAGS	bool	False	Disable task_name tags entirely
CELERY_OUTBOX_MONITORED_TASKS	set[str]	None	Allowlist of task names for tags (others become "other")