SDK Reference - Sluice

Installation

pip install sluice-celery

Requirements:

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.

Both parameters are keyword-only (no positional arguments).

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.

The resolution order is: explicit parameter > environment variable. If neither is set, 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.

Configuration errors are the only exceptions the SDK raises. All runtime errors — network failures, API errors, serialization issues — are caught and logged. The SDK never crashes your Celery worker.

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

​Installation

​sluice.init()

​Parameters

​Environment variables

​Behavior

​Exceptions

​Celery state mapping

​Supported versions

​Where to call init()

Installation

`sluice.init()`

Parameters

Environment variables

Behavior

Exceptions

Celery state mapping

Supported versions

Where to call `init()`