Documentation Index
Fetch the complete documentation index at: https://docs.sluice.sh/llms.txt
Use this file to discover all available pages before exploring further.
Installation
pip install sluice-celery
- Python 3.11, 3.12, or 3.13
- Celery 5.3 or later
- urllib3 2.0 or later (installed automatically)
sluice.init()
The single public API for V0. Call this once at application startup, before Celery workers begin processing tasks.
import sluice
sluice.init(
api_key="sk_live_...",
connection_id="550e8400-e29b-41d4-a716-446655440000",
)
Parameters
| Parameter | Type | Default | Description |
|---|
api_key | str | None | None | Your Sluice API key. Falls back to the SLUICE_API_KEY environment variable. |
connection_id | str | None | None | Your Sluice connection UUID. Falls back to the SLUICE_CONNECTION_ID environment variable. Found in the dashboard under Connections. |
Environment variables
| Variable | Description |
|---|
SLUICE_API_KEY | Fallback for api_key parameter. Use this to keep secrets out of code. |
SLUICE_CONNECTION_ID | Fallback for connection_id parameter. |
init() raises SluiceConfigError.
Behavior
When sluice.init() is called, the SDK:
-
Validates configuration — checks that
api_key and connection_id are non-empty and that the connection ID is a valid UUID. Raises SluiceConfigError immediately if validation fails.
-
Detects framework — checks whether Django is installed. If Django is detected, the SDK eagerly installs its Celery Bootstep on the current Celery app.
-
Connects to
celeryd_init signal — regardless of framework, the SDK registers a handler on Celery’s celeryd_init signal. This fires when each worker process starts and installs the monitoring Bootstep.
-
Auto-configures Celery — the Bootstep sets three critical flags that are
False by default in Celery:
| Celery Setting | Set To | Why |
|---|
worker_send_task_events | True | Enables the event stream — without this, Sluice receives nothing. |
task_send_sent_event | True | Emits a task-sent event when a task is dispatched, allowing Sluice to distinguish “sent but not started” from “unknown”. |
task_track_started | True | Emits a task-started event, enabling execution time tracking. |
-
Captures and forwards events — listens to all Celery task and worker events, normalizes them to Sluice’s unified model, batches them, and sends them to the Sluice API over HTTPS.
Call init() only once. If called multiple times, the SDK logs a warning and ignores subsequent calls. Only the first invocation takes effect.
Exceptions
| Exception | When | Impact |
|---|
SluiceConfigError | API key or connection ID is missing/invalid | Raised at startup — blocks init(). Your worker still starts normally, but monitoring is not active. |
Celery state mapping
The SDK maps Celery’s native task states to Sluice’s unified model:
| Celery State | Sluice State | Notes |
|---|
PENDING | unknown | Celery’s PENDING means “no information about this task” — not “waiting in queue”. This is a critical distinction. |
RECEIVED | queued | Worker received the task but hasn’t started executing it. |
STARTED | active | Task is currently executing (requires task_track_started=True). |
SUCCESS | completed | Task finished successfully. |
FAILURE | failed | Task raised an exception. |
RETRY | retrying | Task will be retried. |
REVOKED | cancelled | Task was revoked by the user or system. |
REJECTED | failed | Worker rejected the task (usually a configuration issue). |
Supported versions
| Dependency | Minimum | Tested |
|---|
| Python | 3.11 | 3.11, 3.12, 3.13 |
| Celery | 5.3 | 5.3, 5.4, 5.5, 5.6 |
| Redis broker | Any | Redis 6+, Redis 7+ |
| RabbitMQ broker | Any | Not tested in V0 — events should work but are not validated |
Where to call init()
The init() call must execute before Celery workers start. The exact location depends on your framework:
| Framework | Location | Example |
|---|
| Django | settings.py or the Celery app module (celery.py) | sluice.init() after CELERY_BROKER_URL is set |
| FastAPI | Application entrypoint (main.py) | Top-level, before app = FastAPI() |
| Flask | Application factory or entrypoint | Inside create_app() or at module level |
| Standalone Celery | celeryconfig.py or tasks.py | Alongside your Celery app definition |
