# sluice-celery

The Python SDK for [Sluice](https://sluice.sh) — monitoring and alerting for Celery job queues.

Two lines of code. No infrastructure changes. Full visibility into every task, queue, and worker.

## Install

```bash
pip install sluice-celery
```

## Quick start

```python
import sluice

sluice.init(api_key="sk_live_...")
```

That's it. The SDK auto-configures Celery's event system and starts streaming task data to the Sluice dashboard. No code changes to your tasks, no new workers to deploy, no Redis configuration.

## What it does

- **Auto-enables Celery events** (`worker_send_task_events`, `task_send_sent_event`, `task_track_started`) so you don't have to
- **Streams task lifecycle events** (queued, started, completed, failed, retried) to the Sluice dashboard in real time
- **Never crashes your workers** — every code path is wrapped in exception handling. If Sluice is down, your tasks run normally
- **Zero performance overhead** — events are batched and sent asynchronously from a background thread. Task execution is never blocked
- **No PII captured** — task arguments and results are never sent. Only task names, states, timestamps, and tracebacks

## Safety guarantees

The SDK runs inside your Celery workers. A bug in our code could take down your payment queue. We take that seriously:

- All signal handlers are wrapped in `try/except` — a Sluice bug never propagates to your task
- The background flush thread is a daemon thread — it won't prevent worker shutdown
- Memory usage is bounded — the event buffer has a hard cap, and a memory guard disables capture if RSS grows beyond a threshold
- Graceful degradation — if the Sluice API is unreachable, events are dropped silently. Your tasks keep running

## Requirements

- Python 3.11+
- Celery 5.3+

## Configuration

```python
import sluice

sluice.init(
    api_key="sk_live_...",          # Required. Or set SLUICE_API_KEY env var
    connection_id="your-conn-uuid", # Required. Or set SLUICE_CONNECTION_ID env var
)
```

Or configure entirely via environment variables — no code changes needed:

```bash
export SLUICE_API_KEY=sk_live_...
export SLUICE_CONNECTION_ID=your-connection-uuid
```

The SDK detects Django and standalone Celery automatically.

## Documentation

- [Full documentation](https://docs.sluice.sh)
- [Quickstart guide](https://docs.sluice.sh/quickstart/sdk)
- [SDK safety model](https://docs.sluice.sh/sdk/safety)
- [Troubleshooting](https://docs.sluice.sh/troubleshooting/common-errors)

## Links

- [Sluice Dashboard](https://sluice.sh)
- [Bug reports & feature requests](https://github.com/sluicehq/sluice/issues)
- [Status page](https://status.sluice.sh)

## License

Apache 2.0
