Metadata-Version: 2.4
Name: sluice-celery
Version: 0.1.0
Summary: Celery monitoring SDK — see your queues, debug failed tasks, get alerts
Project-URL: Homepage, https://sluice.sh
Project-URL: Documentation, https://docs.sluice.sh
Project-URL: Repository, https://github.com/sluicehq/sluice
Project-URL: Issues, https://github.com/sluicehq/sluice/issues
Project-URL: Changelog, https://github.com/sluicehq/sluice/releases
Author-email: Sluice <hello@sluice.sh>
License-Expression: Apache-2.0
Keywords: alerting,celery,monitoring,observability,sluice,task-queue
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Monitoring
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: celery>=5.3
Requires-Dist: urllib3>=2.0
Provides-Extra: test
Requires-Dist: mypy>=1.10; extra == 'test'
Requires-Dist: pytest-cov>=6.0; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# 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
