Metadata-Version: 2.4
Name: celery-uptime
Version: 0.0.1
Summary: Embedded HTTP uptime checks for Celery worker and beat processes
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/Lrakotoson/celery-uptime
Project-URL: Repository, https://github.com/Lrakotoson/celery-uptime
Project-URL: Issues, https://github.com/Lrakotoson/celery-uptime/issues
Project-URL: Changelog, https://github.com/Lrakotoson/celery-uptime/blob/main/CHANGELOG.md
Keywords: celery,healthcheck,readiness,uptime,docker,monitoring
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Celery
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: celery>=5.3
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn>=0.22
Provides-Extra: redis
Requires-Dist: redis>=4.5.2; extra == "redis"
Provides-Extra: sqs
Requires-Dist: boto3>=1.26.143; extra == "sqs"
Requires-Dist: kombu[sqs]>=5.5.0; extra == "sqs"
Provides-Extra: kafka
Requires-Dist: kombu[confluentkafka]>=5.5.0; extra == "kafka"
Provides-Extra: sqlalchemy
Requires-Dist: sqlalchemy<2.1,>=1.4.48; extra == "sqlalchemy"
Provides-Extra: django
Requires-Dist: Django>=2.2.28; extra == "django"
Provides-Extra: mongodb
Requires-Dist: pymongo>=4; extra == "mongodb"
Provides-Extra: elasticsearch
Requires-Dist: elasticsearch<10,>=8; extra == "elasticsearch"
Provides-Extra: cassandra
Requires-Dist: cassandra-driver<4,>=3.25; extra == "cassandra"
Provides-Extra: memcache
Requires-Dist: python-memcached>=1.61; extra == "memcache"
Provides-Extra: all
Requires-Dist: redis>=4.5.2; extra == "all"
Requires-Dist: boto3>=1.26.143; extra == "all"
Requires-Dist: kombu[confluentkafka,sqs]>=5.5.0; extra == "all"
Requires-Dist: sqlalchemy<2.1,>=1.4.48; extra == "all"
Requires-Dist: Django>=2.2.28; extra == "all"
Requires-Dist: pymongo>=4; extra == "all"
Requires-Dist: elasticsearch<10,>=8; extra == "all"
Requires-Dist: cassandra-driver<4,>=3.25; extra == "all"
Requires-Dist: python-memcached>=1.61; extra == "all"
Dynamic: license-file

# celery-uptime

`celery-uptime` adds lightweight HTTP health and readiness endpoints to Celery
workers and beat without changing the Celery command you already run.

```python
from celery import Celery
from celery_uptime import monitor

app = Celery("my-service", broker="sqs://", backend="redis://redis:6379/0")

monitor(app)
```

Then keep your normal command:

```bash
celery -A my_service.celery_app worker --loglevel=info
```

The package starts an embedded Uvicorn server from Celery lifecycle signals. It
starts on `worker_ready` for workers and `beat_init` for beat.

## Installation

The base package only installs Celery, FastAPI, and Uvicorn. Install the extras
matching the providers your Celery app already uses:

```bash
pip install "celery-uptime[redis,sqs]"
```

Available extras:

- `redis`: Redis broker/backend and Redis Sentinel.
- `sqs`: SQS broker.
- `kafka`: Kafka broker through Kombu's Confluent Kafka transport.
- `sqlalchemy`: SQLAlchemy/database result backend.
- `django`: Django database/cache result backends.
- `mongodb`: MongoDB result backend.
- `elasticsearch`: Elasticsearch result backend.
- `cassandra`: Cassandra result backend.
- `memcache`: Memcached cache result backend.
- `all`: all optional provider dependencies.

Missing provider dependencies do not crash the monitor. `/ready` returns a
failing check with details such as `missing_extra:mongodb`.

## Endpoints

- `GET /health`: returns process/server liveness.
- `GET /ready`: returns Celery process readiness plus broker/backend checks.

Example `/ready` response:

```json
{
  "status": "ok",
  "service": "my-service-celery-worker",
  "process": "worker",
  "checks": {
    "celery_process": {"status": "ok", "detail": "ready"},
    "broker": {"status": "ok", "detail": "ok"},
    "backend": {"status": "ok", "detail": "ok"}
  }
}
```

## Configuration

Environment variables:

- `CELERY_UPTIME_ENABLED=true`
- `CELERY_UPTIME_HOST=0.0.0.0`
- `CELERY_UPTIME_PORT=8090`
- `CELERY_UPTIME_SERVICE=<celery app main>-celery-<worker|beat>`
- `CELERY_UPTIME_LOG_LEVEL=warning`
- `CELERY_UPTIME_CHECK_INTERVAL=30`
- `CELERY_UPTIME_CHECK_TIMEOUT=5`
- `CELERY_UPTIME_STALE_AFTER=90`

Docker Compose example:

```yaml
services:
  celery-worker:
    command: ["celery", "-A", "my_service.celery_app", "worker", "--loglevel=info"]
    environment:
      - CELERY_UPTIME_PORT=8090
    ports:
      - "49211:8090"
    healthcheck:
      test: ["CMD-SHELL", "python -c \"import urllib.request; urllib.request.urlopen('http://127.0.0.1:8090/health', timeout=5).read()\" || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

If your image includes `curl`, the healthcheck can be shorter:

```yaml
services:
  celery-worker:
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS --max-time 5 http://127.0.0.1:8090/health > /dev/null || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
```

Use `/health` for Docker/container liveness. It does not run broker/backend
checks and is the safer endpoint for long-running task workers. Use `/ready`
from external monitoring systems such as Uptime Kuma when you want dependency
visibility and alerting. Avoid wiring `/ready` failures directly to automatic
worker restarts unless your task loss/retry behavior is intentionally designed
for that.

External readiness check examples:

```bash
curl -fsS --max-time 5 http://127.0.0.1:8090/health
curl -fsS --max-time 5 http://127.0.0.1:8090/ready
```

`/ready` is served from a cache populated by a background probe loop, so HTTP
requests do not block on broker/backend clients. Before the first probe it
returns `503` with `detail: "not_checked_yet"`. If the cached probe result is
older than `CELERY_UPTIME_STALE_AFTER`, it returns `503` with `detail: "stale"`.

## Automatic Checks

`monitor(app)` automatically detects:

- RabbitMQ/AMQP broker: `amqp://`, `pyamqp://`, `librabbitmq://`.
- Redis broker/backend: `redis://`, `rediss://`.
- Redis Sentinel broker/backend: `sentinel://` with `master_name`.
- SQS broker: `sqs://` with `broker_transport_options`.
- Kafka broker: `kafka://`, `confluentkafka://`.
- SQLAlchemy/database backend: `db+...`, `database+...`.
- Django backend conventions: `django-db`, `django-cache`.
- RPC backend: `rpc://`, checked through broker connectivity.
- Memcached backend: `cache+memcached://`, `cache+pymemcache://`, `cache+pylibmc://`.
- MongoDB backend: `mongodb://`, `mongodb+srv://`.
- Elasticsearch backend: `elasticsearch://`.
- Cassandra backend: `cassandra://`.

No result backend is valid Celery configuration. If `result_backend` is absent
or `disabled://`, `/ready` reports the backend as healthy and non-required:

```json
{"status": "ok", "detail": "disabled", "required": false}
```

Unsupported providers outside this classic set fail closed in `/ready` unless
you replace them with explicit checks.

## Explicit Checks

For unusual apps, pass explicit checks:

```python
from celery_uptime import database_check, monitor, redis_check, sqs_check

monitor(
    app,
    checks=[
        sqs_check(
            "broker",
            endpoint_url="https://sqs.fr-par.scw.cloud",
            region="fr-par",
            queue_url="https://sqs.fr-par.scw.cloud/queue",
            access_key="...",
            secret_key="...",
        ),
        redis_check("backend", "redis://redis:6379/0"),
        database_check("reporting-db", "postgresql://user:password@db:5432/app"),
    ],
    include_auto_checks=False,
)
```

Provider checks are connection-only. They do not write/read/delete Celery result
records or mutate broker/backend data.

