Metadata-Version: 2.5
Name: celery-healthcheck
Version: 0.3.0
Summary: A lightweight HTTP health check server for Celery workers, designed to work with cloud platforms that only support TCP-based health probes
Project-URL: Repository, https://github.com/iloveitaly/celery-healthcheck
Author-email: Michael Bianco <mike@mikebian.co>
License: MIT
License-File: LICENSE.md
Keywords: azure,celery,fastapi,health-check,healthcheck,monitoring,worker
Requires-Python: >=3.9
Requires-Dist: celery>=5.5.0
Requires-Dist: fastapi>=0.115.12
Requires-Dist: uvicorn>=0.34.0
Description-Content-Type: text/markdown

# Celery Healthcheck

A lightweight HTTP health check server for Celery workers, designed to work with cloud platforms like Azure that only support TCP-based health probes.

## Problem

When deploying Celery workers to cloud platforms like Azure, you need a way to verify the worker's health. However, Azure doesn't allow command execution for health checks and only supports TCP-based probes. This makes it challenging to properly monitor Celery workers.

## Solution

`celery-healthcheck` spins up a small FastAPI server within each Celery worker that exposes an HTTP endpoint to check the worker's health status. This allows cloud platforms to perform health checks via HTTP requests rather than command execution.

Importantly, the ping-based healthcheck reports whether the worker is connected to the broker and responsive. However, it does not guarantee that the worker is processing tasks successfully nor does it indicate a problem with the Celery worker itself, as the ping can fail for reasons like the broker being unavailable. It is not recommended to autoheal the Celery worker based on the healthcheck due to the noise inherent in this signal.

## Installation

```bash
pip install celery-healthcheck
```

## Usage

Add the health check server to your Celery application:

```python
from celery import Celery
import celery_healthcheck

app = Celery('myapp')
app.config_from_object('myapp.celeryconfig')

# Register the health check server
celery_healthcheck.register(app)
```

Now start your worker as usual

```sh
celery -A myapp worker -l info
```

## How It Works

The health check server:

1. Embeds a FastAPI application inside your Celery worker
2. Runs on port 9000 by default (configurable)
3. Exposes an HTTP endpoint (`GET /`) that:
   - Uses Celery's inspect API to ping the current worker only
   - Returns a JSON response with status and result

## API Endpoints

### GET /

Pings the Celery worker and returns its status.

**Response:**

```json
{
  "status": "ok",  // or "error" if worker doesn't respond
  "result": { ... } // Raw response from Celery's ping command
}
```

## Configuration

The health check app can be configured via the main celery app it is registered on.

- `healthcheck_port`: The port on which the health check server will listen (default: 9000)
- `healthcheck_ping_timeout`: The timeout for the ping command to the worker (default: 2.0 seconds)

## Beat Health Check

`celery-healthcheck` also supports adding a liveness probe for `celery beat`.

It works by hooking Celery's `beat_init` signal and patching the `tick()` method on whichever scheduler instance beat actually constructs, so it works identically with the stock scheduler, [django-celery-beat](https://github.com/celery/django-celery-beat), [redbeat](https://github.com/sibson/redbeat), or any custom scheduler.

This method ensures that the liveness probe reflects whether beat is still actively scheduling tasks.

```python
from celery import Celery
import celery_healthcheck

app = Celery('myapp')
app.config_from_object('myapp.celeryconfig')

celery_healthcheck.register(app)
```

```sh
celery -A myapp beat -l info
```

### GET / (Beat)

Reports whether beat has ticked recently.

**Response:**

```json
{
  "status": "ok",           // or "error"
  "last_tick_age": 4.2,     // seconds since the last tick
  "max_tick_age": 610.0     // staleness threshold currently in effect
}
```

### Beat Configuration

- `healthcheck_beat_port`: The port on which the beat health check server will listen (default: 9001)
- `healthcheck_beat_max_tick_age`: Explicit override for the staleness threshold, in seconds. If unset, it's derived from the scheduler's own `max_interval` instead (see below).
- `healthcheck_beat_tick_age_multiplier`: Multiplier applied to the scheduler's `max_interval` when deriving the default threshold (default: 2.0)

> [!WARNING]
> `tick()` sleeps up to the scheduler's `max_interval` between calls when nothing is due — stock Celery defaults this to 300 seconds, while `django-celery-beat` and similar backends are typically much shorter. Setting `healthcheck_beat_max_tick_age` below your scheduler's `max_interval` will cause false-positive failures on a healthy beat process. The default (`max_interval * healthcheck_beat_tick_age_multiplier + 10s` grace period) is derived automatically per-scheduler so this shouldn't need tuning in most setups.

## Azure Configuration

When configuring Azure health probes:

1. Set the probe to use HTTP
2. Point to port 9000
3. Use the path "/"
4. A 200 OK response indicates the worker is healthy

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

### Development tasks

Run tests

```sh
uv run pytest
```

Format

```sh
uvx ruff format
```
