celery-exporter: Celery task metrics for Prometheus, from the broker's own event stream

It reads the broker's event stream rather than instrumenting your code

The why section explains the motivation in a way that tells you exactly what the tool is. While adding Celery monitoring to a client site, the author found that the existing brokers either did not work, exposed incorrect metric values, or did not expose the metrics needed. So they wrote an exporter that essentially wraps the built-in Celery monitoring API and exposes all of the event metrics to Prometheus in real time. The design consequence is important. Nothing in your task code changes, and the exporter is a separate process that subscribes to the broker's event stream. That means the metrics describe what Celery itself observed, and the cost is that Celery must be configured to send those events in the first place. The feature list says it is tested for both Redis and RabbitMQ, and that it follows the Prometheus exporter best practices, with deployment as a Docker image or a Python single-file binary built through PyInstaller, and a health check endpoint at /health.

Enabling events, and the one that is off by default

Celery needs to be configured to send events to the broker, which the exporter then collects, and there are two ways to do it. The CLI route is a single command.

$ celery -A <myproject> control enable_events

There is a catch the README flags. By default this does not send the task-sent event, which has to be configured separately, while the other events work out of the box. In the Celery configuration file the two settings are the worker send task events flag and the task send sent event flag.

# In celeryconfig.py
worker_send_task_events = True
task_send_sent_event = True

And in a Django project the same two settings appear in settings.py under the CELERY_ prefix.

# In settings.py
CELERY_WORKER_SEND_TASK_EVENTS = True
CELERY_TASK_SEND_SENT_EVENT = True

So the one that is off by default is the counter for published tasks, and without it the sent metric stays at zero while the rest of the pipeline works.

Running it, as a container, a binary or a package

There are three ways to run the exporter. As a Docker image, the port 9808 is published and the broker URL is passed as a flag.

docker run -p 9808:9808 danihodovic/celery-exporter --broker-url=redis://redis.service.consul/1

For a non-Docker environment there is a single-file binary built with PyInstaller that you download and make executable.

curl -L https://github.com/danihodovic/celery-exporter/releases/download/latest/celery-exporter -o ./celery-exporter
chmod +x ./celery-exporter
./celery-exporter --broker-url=redis://redis.service.consul/1

And the package is on PyPI under the name prometheus-exporter-celery.

pip install prometheus-exporter-celery

The Helm chart for Kubernetes lives in the charts directory of the repository under charts/celery-exporter. Every argument can also be given as an environment variable with a CE_ prefix, so the broker URL becomes an environment setting in a container.

docker run -p 9808:9808 -e CE_BROKER_URL=redis://redis danihodovic/celery-exporter

To check it works, you scrape the metrics endpoint directly.

curl 127.0.0.1:9808/metrics

Broker transport options, including the Sentinel case

The default broker options suit most cases, but the exporter can pass transport options straight through to Kombu. You give one or more broker transport option parameters, and the example sets a global key prefix and a visibility timeout.

docker run -p 9808:9808 danihodovic/celery-exporter --broker-url=redis://redis.service.consul/1 \
  --broker-transport-option global_keyprefix=danihodovic \
  --broker-transport-option visibility_timeout=7200

Extended options such as sentinel_kwargs are passed as a JSON string, which is the case for a Redis Sentinel deployment.

docker run -p 9808:9808 danihodovic/celery-exporter --broker-url=sentinel://sentinel.service.consul/1 \
  --broker-transport-option master_name=my_master \
  --broker-transport-option sentinel_kwargs="{\"password\": \"sentinelpass\"}"

The list of available options is documented in the Kombu Redis transport reference. There is also a retry interval parameter, and the default behaviour matters here. By default the exporter raises an exception and exits if there are any errors communicating with the broker, so in a container that means a crash loop rather than a degraded exporter.

docker run -p 9808:9808 danihodovic/celery-exporter --broker-url=redis://redis.service.consul/1 \
  --retry-interval=5

The metric names, and what a queue wait histogram excludes

The metrics table is mostly a direct mapping from Celery events to Prometheus types. There is a counter for a task message published, one for the worker receiving a task, one sent just before execution, one on success and one on failure, one for a task rejected by the worker that may be re-queued or moved to a dead letter queue, one for a revoked task and one for a task that failed but will be retried. Then there are two gauges, celery_worker_up which indicates if a worker has recently sent a heartbeat, and celery_worker_tasks_active for the number of tasks a worker is currently processing. Two histograms follow, one for task runtime and one for the time tasks spend waiting in the queue before execution. The queue wait metric has a documented exclusion, deliberate ETA or countdown delay is not counted, and a retry backoff is delivered as an ETA so it is excluded too. That detail matters when you alert on queue wait, because a task scheduled for later will not look like a slow queue.

Dashboards, alerts and a project structure that mixes several tools

The operational assets come from a mixin repository in the celery-mixin subdirectory. The alerting rules are in a prometheus-alerts.yaml file there, and by default they alert when a task failed in the last ten minutes and when no Celery workers are online, both of which you are told to tweak to suit your case. The Grafana dashboards are published separately, one for the view shown in the README image and another for an overview of Celery tasks, and both can be imported directly into a Grafana instance. The repository itself is a polyglot build, with a poetry managed project, a Taskfile.yml, a buildInstaller.sh, two Dockerfiles including one for the PyInstaller build, a docker-compose.yml that runs Redis and RabbitMQ for development, jsonnetfile files, a vendor directory, a cli.py entry point, a src directory, and a charts directory for the Helm chart. The pyproject pins Python from 3.11 up to but not including 3.15, and the Docker image builds on a slim Debian Python base and runs as a non-root user. The licence is MIT and the last push was on 2026-10-09.

Editorial conclusion

celery-exporter fits a team running Celery that wants queue depth, task outcomes and worker liveness in Prometheus without instrumenting every task by hand. It does not fit a Celery deployment that has not enabled event reporting, because without those events there is nothing to scrape, and it does not fit a setup that needs per-task business metrics, since it reports framework events rather than your payloads. Verify first that your broker permits the monitoring subscription, enable the sent event as well as the others if you want the published counter, and start with the health endpoint before wiring the scrape target into Prometheus.

Frequently asked questions

Official sources

1. danihodovic/celery-exporter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases