stemtrace

Zero-infrastructure Celery task flow visualizer

Flower shows you what exists. Stemtrace shows you what happened.

Stemtrace captures your task executions as a graph: visualize parent→child flows, see retry chains, track groups and chords, all without adding any new infrastructure.

It records each task's lifecycle (sent, started, retried, finished) with its arguments, result and exception, and sends these events through the Redis or RabbitMQ broker you already run. The dashboard runs as its own server or inside your FastAPI app. No database is needed.

What it helps you debug

The features page shows each dashboard view with screenshots.

Is it ready for production?

What it adds to your system:

• On workers: events are published from Celery's task signals. Events that can't be published are dropped, not buffered. Each network step of a publish has a 2s timeout (name lookups under uWSGI are the exception; see Brokers), and three failures in a row make the worker skip publishing for a cooldown that grows from 1s to 30s. So during an outage each worker process makes at most three bounded attempts and then one per cooldown. Logging is bounded: at most four warnings a minute. On RabbitMQ, an event costs about 0.3 ms on the process's connection. Brokers has the details and limitations for each broker.
• On your broker: one Redis stream, or a RabbitMQ fanout exchange with a queue per server host, named with the stemtrace prefix by default.
• The dashboard is read-only: it never modifies your task queue. Values under argument and dict keys named like secrets (password, api_key, token, …) appear as [Filtered]. It has a built-in login page with sign-in throttling, or takes your own FastAPI auth dependency, and a health endpoint for your monitoring. See Security.

What to know before you rely on it:

• History is kept in memory, up to 10,000 tasks by default. A server restart starts empty: with Redis it replays the events still in the stream; with RabbitMQ, events it already consumed are gone. See Event retention.
• The dashboard keeps its state in one process, with the event consumer inside it. A multi-process mode is planned. Don't embed it in an app that runs several worker processes; see Running several processes.
• Scrubbing goes by key name only. Values that aren't dicts, lists or tuples, whether positional arguments or return values (e.g. the password in login.delay("alice", "hunter2")), exception messages, tracebacks and task output are shown as they are. That's why capturing output is opt-in.
• Limitations are documented next to each feature, for example graph edge cases with task.replace() and older Celery versions in Graphs.
• stemtrace is pre-1.0. Read the version's notes in the CHANGELOG before you upgrade.

stemtrace, Flower, or another tool?

Use stemtrace to understand how a workflow ran: which task started which, why a task retried, and where a chord stopped.

Other tools fit better when you want to:

• Watch workers live and act on them (revoke tasks, change pool sizes or rate limits): use Flower. stemtrace is read-only. The two can run side by side; see Running next to Flower.
• Alert on queue length, throughput or failure rates: use a metrics exporter for Celery and your existing alerting. stemtrace doesn't alert; its health endpoint only reports on stemtrace's own event consumer.
• Trace a request across services, from an HTTP call to the tasks it queued: use OpenTelemetry's Celery instrumentation with your tracing backend.
• Keep task history for weeks or months: stemtrace keeps recent tasks in memory.

Quick start

1. Install

# Using pip
pip install stemtrace

# Using uv
uv add stemtrace

2. Instrument your Celery app

from celery import Celery
import stemtrace

app = Celery("myapp", broker="redis://localhost:6379/0")

# One line to enable event capture.
# Tip: put this in the module where you define your Celery app so it's imported by
# both Celery workers and any code that calls app.send_task()/delay().
stemtrace.init_worker(app)

3. View the dashboard

Option A: Standalone server (new container/process)

stemtrace server

Open http://localhost:8000.

Tip: make sure the server is pointed at the same broker as your workers:

stemtrace server --broker-url redis://localhost:6379/0
# or:
stemtrace server --broker-url amqp://guest:guest@localhost:5672//

Option B: Embed in your FastAPI app (no extra container)

from fastapi import FastAPI
import stemtrace

app = FastAPI(lifespan=my_lifespan)  # Your existing app

stemtrace.init_app(app, broker_url="redis://localhost:6379/0")

Access at /stemtrace/ in your existing app, with no new services to deploy.

Adding stemtrace to a project that's already in production? Read Adopting stemtrace in an existing project first: it covers which processes need the package, version requirements, and what changes on your broker. See Deployment for Docker, auth, reverse proxies and health checks.

Documentation

Planned work and ideas are tracked in GitHub issues. Open one, or comment on an existing one, to say what you'd use.

Contributing

Contributions, bug reports, and feature requests are welcome! This is a community project: if stemtrace helps you debug Celery, consider helping make it better.

See our Contributing Guide to get started.

git clone https://github.com/iansokolskyi/stemtrace.git
cd stemtrace
uv sync --extra dev   # Install dependencies
make check            # Run tests

License

MIT: use it however you like.