DEV Community: Mahmoud Ahmed

celery-manager: See, Control and Pause Your Celery Tasks Without Touching Your Beat Schedule

Mahmoud Ahmed — Mon, 26 Oct 2026 13:52:38 +0000

celery-manager: See, Control and Pause Your Celery Tasks Without Touching Your Beat Schedule

A dashboard and control API for Celery, for Django, Flask and FastAPI projects.

Celery is great until you need to know what it's actually doing.

A task failed overnight. Which arguments did it get? Which worker ran it? What did it log before the traceback? A customer import has been running for 20 minutes. Is it at row 10 or row 10,000? And one I hit all the time: "Can we skip tomorrow's 9:00 report, just once?" Usually that means editing the beat schedule, deploying, remembering to revert it, and deploying again.

I built celery-manager to answer those questions from one screen. It's a dashboard and control API for Celery that shows what every task is doing, lets you act on tasks, and can pause a single upcoming run of a periodic task without changing your beat schedule or restarting anything.

It works with any Django, Flask or FastAPI project that already uses Celery.

What you get

🔍 Every run is visible, whether or not the task is decorated: status, arguments, worker, queue, timings, exceptions and full tracebacks.
🗂 History and search: paginated history, filters by status, task name or time range, and free-text search over names, IDs and arguments.
📈 Live progress: call report_progress() inside a task and watch a progress bar move.
📝 Log capture: a task's logging output is shown next to the run.
🎛 Control: start any registered task, cancel or terminate runs, and retry them as they were or with edited arguments, one at a time or in bulk.
⏸ Schedule control: skip one upcoming periodic run, or pause a whole schedule until you resume it or until a set time.
🌳 Workflows: chains, groups and chords drawn as a tree on each run's page.
📊 Insights: volume, success rate and runtimes over time, a page for each task, and failures grouped by cause with "retry all".
👷 Workers and queues: live worker state, pool controls, runtime rate limits, queue depth and purge.
🔗 Share and export: filters live in the URL, plus saved views and CSV or JSON export.
🧾 Audit log: every control action is recorded with the user who took it.
🎨 Light and dark themes, plus your own wordmark, accent colour and logo.

How it works: three small parts

celery-manager has three parts that share one SQLAlchemy-backed store (SQLite by default, or PostgreSQL, MySQL, or any database SQLAlchemy supports):

REST API and dashboard. A FastAPI app that serves the JSON API under /api and the dashboard at /. You can mount it in your own app or run it standalone.
Events listener (celery-manager events). A long-running process that records status changes from Celery's event bus, for every task, decorated or not.
The @track decorator. Optional and per task. It adds log capture, enables pausing and cancelling individual scheduled runs, and records the run as started before your function runs.

Because the listener works from Celery's own events, you get visibility into existing tasks without changing any task code. @track is only for the extra features.

Quickstart

1. Install

pip install --pre celery-manager

# optional extras
pip install --pre "celery-manager[standalone]"   # adds uvicorn
pip install --pre "celery-manager[flask]"        # adds Flask and a2wsgi

2. Create the dashboard app

import os

from celery_manager.config import CeleryManagerConfig
from celery_manager.api.app import create_app

config = CeleryManagerConfig(
    celery_app=your_celery_app,
    db_url="sqlite:///celery_manager.db",  # or any SQLAlchemy URL
    secret_key=os.environ["CELERY_MANAGER_SECRET_KEY"],  # private + random
)
app, _ = create_app(config)

Generate a secret key:

python -c "import secrets; print(secrets.token_urlsafe(32))"

create_app refuses to start if the key is empty or still the "change-me" placeholder.

Serve it with any ASGI server:

uvicorn your_module:app

Local development over plain HTTP? The session cookie is Secure by default, so your browser won't send it to http://localhost and you'll look logged out after signing in. Pass cookie_secure=False for local development only.

3. Turn on Celery events

Add these to the Celery config shared by web, worker and beat:

app.conf.worker_send_task_events = True   # same as running the worker with -E
app.conf.task_send_sent_event = True      # publisher emits task-sent (carries the queue)

4. Run the events listener

Run it next to your worker and beat:

celery-manager events --celery-app your_module:your_celery_app --db-url sqlite:///celery_manager.db

Use the same --db-url as in your config.

5. Create your first user

There's no default account, which is intentional. Create one:

from celery_manager.auth.users import create_user
from celery_manager.db.session import init_db, get_session_factory

Session = get_session_factory(init_db(config))
create_user(Session(), "admin", "a-real-password")

Going further with `@track`

Put @track under @app.task, and call celery_manager.setup() in the worker process. create_app() only sets up the dashboard process, so without setup() the decorator does nothing.

# myproject/tasks.py — imported by the Celery worker
import celery_manager
from celery_manager.config import CeleryManagerConfig

from myproject.celery import app

celery_manager.setup(CeleryManagerConfig(
    celery_app=app,
    db_url="sqlite:///celery_manager.db",  # the same DB the dashboard uses
    secret_key="a-real-secret-in-production",
))


@app.task(bind=True)
@celery_manager.track(schedule_name="send-report-every-2-hours")
def send_report(self):
    ...

schedule_name should match the key in your beat_schedule. bind=True is optional, so @track also works on plain tasks:

@app.task
@celery_manager.track()
def send_welcome_email(address):
    ...

Live progress bars

from celery_manager import report_progress


@app.task(bind=True)
@celery_manager.track()
def import_customers(self, row_count: int = 60):
    for row in range(1, row_count + 1):
        handle_row(row)
        report_progress(row, row_count, f"row {row} of {row_count}")
    return f"imported {row_count} rows"

The signature is report_progress(current, total=None, message=None). A few details:

It's throttled. Database writes happen at most once every 0.5 seconds per run, so you can call it in a tight loop. The final call (current >= total) always gets written.
It never raises into your task. A progress problem won't crash a real job.
Leave out total for open-ended work. The dashboard then shows a running count and message instead of a percentage.

Logs and tracebacks next to the run

When a tracked task fails, its page shows the traceback, the captured log output and a Retry button together:

The headline feature: pause a schedule without editing it

celery-manager never edits your beat schedule. Beat keeps sending the task as usual, and @track makes that run skip itself when you've paused it. So there's no config change, no deploy, and nothing to remember to revert.

From the Schedules page you can:

Skip one upcoming run. Open a schedule, see its next runs, and skip or cancel just one. The rest of the schedule carries on.
Pause the whole schedule for 1 hour, until tomorrow at 9:00, or until a custom time.

When you resume, the schedule continues from the current time. Runs missed while paused are not run all at once afterwards.

Full control from the dashboard

Start task. Pick any registered task. Its arguments are prefilled from the function signature, and you can choose a queue or a delay.
Cancel a run that hasn't started, or Terminate one that's already running.
Retry, or Retry with changes to edit the arguments first. You can select several failed runs and retry them together.
Bulk cancel every waiting or running task that matches your filters. The count is shown before you confirm.
Workers. Shut a worker down, add or remove pool processes, and start or stop consuming from a queue.
Rate limits. Change a task's rate limit on running workers without a deploy. The change lasts until the worker restarts.
Purge a queue. You have to type the queue name to confirm, so it's hard to do by accident.

Everything in the dashboard is also available through the REST API, so you can script it or connect it to your own tools.

Workflows, insights and grouped failures

Chains, groups and chords are drawn as a tree, so when one member of a chord fails you can see exactly which one:

Insights show volume, success rate and runtime trends, with a page for each task:

Failures are grouped by exception signature. Instead of 300 separate failed rows, you see "these 300 runs failed with the same ConnectionError", and you can retry the whole group at once:

Plugging it into your stack

The dashboard is a standard ASGI app, so it fits in most places.

FastAPI. Mount it next to your own routes:

from fastapi import FastAPI

from celery_manager.api.app import create_app
from celery_manager.config import CeleryManagerConfig

dashboard, _session_factory = create_app(CeleryManagerConfig(
    celery_app=celery_app,
    db_url="sqlite:///celery_manager.db",
    secret_key=SECRET,
))

app = FastAPI()
app.mount("/celery-manager", dashboard)

Flask. Wrap it with a2wsgi (install celery-manager[flask]):

from a2wsgi import ASGIMiddleware
from flask import Flask
from werkzeug.middleware.dispatcher import DispatcherMiddleware

from celery_manager.api.app import create_app

app = Flask(__name__)
dashboard, _ = create_app(config)

app.wsgi_app = DispatcherMiddleware(app.wsgi_app, {
    "/celery-manager": ASGIMiddleware(dashboard),
})

Django. The recommended setup is to run the dashboard as its own uvicorn process next to Django, optionally behind your reverse proxy:

uvicorn yourmodule:dashboard --port 8001 --root-path /celery-manager

The repository includes a working reference in examples/django_demo/run_dashboard.py.

For live push updates, run the dashboard as its own process rather than through the Flask/WSGI adapter.

Production notes

Use a real database. SQLite is fine for local development. In production, point db_url at PostgreSQL or MySQL.
Run migrations as a deploy step with celery-manager migrate, and set auto_migrate=False so the app doesn't upgrade the schema itself at startup:

  celery-manager migrate --db-url postgresql://admin@db/celery_manager

Keep cookie_secure=True (the default) anywhere outside local development.
macOS tip: with Celery 5.6 and billiard 4.3, prefork workers on macOS can fail every task with ValueError: not enough values to unpack. This is an upstream issue. Use --pool=threads or --pool=solo locally.

Status: early alpha

The current release is 0.1.0a4 and needs Python 3.10+. To be upfront about what that means:

The API may still change.
There's no role system yet. Any signed-in user can perform any action. Every action is recorded in the audit log, but you should still only give access to people you trust.

My recommendation: use it on internal tools for now, and pin the exact version.

Links

⭐ GitHub: github.com/Pythondeveloper6/celery-manager
📦 PyPI: pypi.org/project/celery-manager
📖 Docs: pythondeveloper6.github.io/celery-manager

If you run Celery in production, I'd really like to know what question you most often can't answer about your tasks. That's what decides what I build next. Issues, ideas and stars on GitHub are all welcome.

Thanks for reading!

Mahmoud Ahmed

Meet django-vantage: A Django Admin That Configures Itself

Mahmoud Ahmed — Mon, 26 Oct 2026 13:51:26 +0000

Meet django-vantage: A Django Admin That Configures Itself

Columns, filters, search, charts, Kanban boards, dark mode and a JSON API, without writing an admin.py.

If you've built a few Django projects, you know the routine. You add a model, open admin.py, and type the same things again: list_display, list_filter, search_fields, ordering, list_select_related. Then you do it for the next model, and the one after that.

Django's admin is one of the best features in any web framework. Still, almost every project spends time on two jobs: telling the admin things it could work out from the model, and fixing up a UI that hasn't changed much in years.

So I built django-vantage, a Django admin panel that is smart and beautiful. Every model works with zero configuration. When you want something different, you override only that one thing and Vantage keeps inferring the rest.

In this post I'll show what it does, how it decides what to show you, and how to try it in about a minute.

The idea: smart by default, easy to override

Vantage is built on three principles.

1. Smart. Columns, filters, search fields, sort order, form widgets and query optimisation are all inferred from your model. You don't need any configuration to get a useful admin.

2. Easy. You can override any inferred default on its own. If you set list_display, only the columns change. Filters, search and widgets stay inferred. Inference works per attribute, so customising one thing doesn't mean you have to configure everything.

3. Configurable from the UI. Many settings can also be changed from the panel itself (columns, filters, stats, dashboard, sidebar, branding), so they apply without a deploy. Code and UI configuration combine in one fixed order:

SiteConfiguration row  >  settings.VANTAGE  >  conf.DEFAULTS

Up and running in 60 seconds

Vantage is in alpha, so install it with --pre:

pip install --pre django-vantage

Add it to INSTALLED_APPS, after the Django contrib apps and before your own apps:

# settings.py
INSTALLED_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "vantage",
    # your apps
]

LOGIN_URL = "/accounts/login/"
LOGIN_REDIRECT_URL = "/admin/"

Mount it. You can also include Vantage's styled sign-in, sign-out and password-change views. Their route names match django.contrib.auth.urls, so you can switch back at any time:

# urls.py
from django.urls import include, path
from vantage import site

urlpatterns = [
    path("admin/", site.urls),
    path("accounts/", include("vantage.authviews")),
]

Run migrations. Vantage keeps its own tables for site configuration, the audit log, saved views and per-list preferences:

python manage.py migrate

That's all. Every model in your project now has a list view, a form, filters and search.

No Node.js required. Django is the only runtime dependency, and the CSS and JavaScript ship prebuilt.

How the "smart" part works

Inference follows fixed, documented rules, so you can predict what you'll get. Here is roughly what Vantage does with each model.

Columns (list_display). Every concrete field gets a score and the top six become columns. Choice fields rank highest, followed by booleans, foreign keys, emails and URLs, and short CharFields. Large text, JSON, binary, file and primary-key fields are never shown as columns. Audit timestamps like created_at go last.

The link column (list_link). Vantage looks for a field named name, title, label, headline, subject or display_name. If there isn't one, it uses the first plain CharField. If there's no CharField, it uses the primary key.

Filters (list_filter). Up to five filters: choices and booleans first, then one date field (a domain date such as ships_on is preferred over an audit timestamp), then foreign keys.

Search (list_search). Only text-like fields are searched. Indexed and unique fields come first. Vantage also follows one hop into each foreign key, so you can search orders by customer__name without configuring anything.

Ordering. Vantage uses your Meta.ordering if you set one. Otherwise it sorts newest first on created_at, created, date_joined, timestamp or date. If none of those exist, it sorts by descending primary key.

Queries. select_related and prefetch_related are worked out from the fields the page actually renders, which avoids N+1 queries.

Sensitive fields are never exposed. Fields whose names look like credentials (password, token, api_key, salt, hash, pin, cvv, and others) are never shown, linked, filtered or searched.

You can check the result yourself:

>>> from vantage import inference
>>> inference.infer_all(Order)
{'list_display': ['number', 'status', 'customer', 'shipping_city', 'total', 'created_at'],
 'list_link': 'number',
 'list_filter': ['status', 'created_at', 'customer'],
 'list_search': ['number', 'shipping_city', 'note', 'customer__name'],
 'ordering': ['-created_at']}

See it, then own it: `vantage_scaffold`

My favourite command in the project:

python manage.py vantage_scaffold shop            # print what was inferred
python manage.py vantage_scaffold shop --write    # save it as shop/panel.py

It prints a real panel.py that contains everything Vantage inferred:

@register(Order)
class OrderPanel(ModelPanel):
    list_display = [
        "number",
        "status",
        "customer",
        "shipping_city",
        "total",
        "created_at",
    ]
    list_link = "number"
    list_filter = ["status", "created_at", "customer"]
    list_search = ["number", "shipping_city", "note", "customer__name"]
    ordering = ["-created_at"]

The file is ordinary code. Edit whatever you want, and delete any attribute to hand it back to inference. If you delete the whole file, your models stay registered.

Overriding only what you care about

Create a panel.py next to your models.py:

# blog/panel.py
from vantage import ModelPanel, register

from blog.models import Post


@register(Post)
class PostPanel(ModelPanel):
    icon = "file-text"
    group = "Content"
    list_display = ["title", "author", "status", "published_at"]

Only the columns change. Filters, search, sorting and form widgets are still inferred.

Run python manage.py check and Vantage validates your panels and settings, including typo suggestions:

Unrecognised key(s) in the VANTAGE setting:
  'SITE_TTLE' is not a Vantage setting. Did you mean 'SITE_TITLE'?

A tour of the features

A real data grid

The list view gives you saved views, grouping, density settings, a column picker, inline editing, and trash and restore. Bulk actions can apply to all matching rows, not just the current page. Select 40,000 filtered records and act on all of them.

There's also a command palette for jumping to any model or record from the keyboard:

Stats and charts, declared in Python

You declare stat cards and charts on the panel, and they're computed on the rows currently filtered. Charts render as inline SVG with no JavaScript charting library.

from django.db.models import Avg, Count, Q, Sum
from vantage import Chart, ModelPanel, Stat, register


@register(Order)
class OrderPanel(ModelPanel):
    list_stats = [
        Stat("Revenue", Sum("total"), format="currency", trend="created_at"),
        Stat("Orders", Count("id")),
        Stat("Average order", Avg("total"), format="currency"),
        Stat("Refunded", Count("id", filter=Q(status="refunded")), tone="destructive"),
    ]

    list_charts = [
        Chart.timeseries("Revenue over time", date="created_at", value=Sum("total")),
        Chart.breakdown("By status", group_by="status", value=Count("id"), kind="donut"),
    ]

trend="created_at" compares the value with the previous period of the same length.
Chart.timeseries picks day, week or month buckets based on the date range of your data, unless you set bucket yourself.
If the ORM can't express what you need, pass a callable: Stat("Churn rate", lambda qs: churn_for(qs), format="percent"). If it raises an exception, the card shows — and the rest of the page still works.

Kanban, calendar, gallery and map views

The same list can be shown as a table, a Kanban board, a month calendar, a gallery or a map. Users pick the grouping field on the page.

@register(Order)
class OrderPanel(ModelPanel):
    list_views = ["table", "kanban", "calendar"]   # first one is the default
    kanban_field = "status"                         # board columns
    calendar_field = "ships_on"                     # where records land
    kanban_fields = ["status", "priority"]          # what "Group by" offers
    card_fields = ["customer", "total"]             # what a card shows

Forms with a layout DSL

Tabs, Tab, Section and Row nest however you like:

from vantage import ModelPanel, Row, Section, Tab, Tabs, register


@register(Post)
class PostPanel(ModelPanel):
    layout = Tabs(
        Tab("Content",
            Section(Row("title", "slug"), "body"),
            Section(Row("status", "published_at"), title="Publishing", collapsed=True),
        ),
        Tab("SEO", Section("meta_title", "meta_description")),
    )

One safety detail I like: fields you leave out of the layout aren't dropped. They're collected into an extra "Other" tab, so a required field can't quietly disappear from the form.

Editable inlines work as you'd expect:

from vantage.inlines import Inline


class OrderItemInline(Inline):
    model = OrderItem
    fields = ["product", "quantity", "unit_price"]
    extra = 1
    max_num = 50


@register(Order)
class OrderPanel(ModelPanel):
    inlines = [OrderItemInline]

Tip: set max_num explicitly on inlines for now. In the current alpha, leaving it unset raises an error.

A cascade-delete preview

Before you delete a record, Vantage shows exactly what else will be deleted. It uses the same Collector as the real delete, so the preview always matches what happens. If a delete is blocked by a protected relation, you get a plain explanation instead of an error page:

"This customer cannot be deleted while Orders still reference it. Remove or reassign those first."

Undo that respects your teammates

Deletes, bulk edits and inline edits show an undo toast. Undo never overwrites a newer change made by someone else in the meantime.

Permissions, roles and sensitive data

Three permission layers, enforced on views, bulk actions and API calls.
Read-only mode and impersonation.
Multi-tenancy that fails closed: if tenant scoping can't be resolved, nothing is shown.
A permission matrix for Django groups, so you can see who can do what in one place.
Sensitive fields such as passwords, tokens and card numbers are masked by default. Revealing one is restricted and logged.

There's also a read-only data-quality audit for each model, and a schema map that shows how your models relate:

A JSON API for every panel

Every panel also has a JSON API that goes through the same permission and validation path as the UI, with cursor pagination and optimistic concurrency. You don't have to keep a separate serializer layer in sync with your admin.

Theming from one colour

Give Vantage a brand colour and it derives full light and dark palettes, adjusting lightness until the text passes WCAG AA contrast (4.5:1). RTL layouts are supported too.

# settings.py
VANTAGE = {
    "SITE_TITLE":  "Acme",
    "LOGO":        "img/acme.svg",
    "LOGO_DARK":   "img/acme-light.svg",
    "BRAND_COLOR": "#0ea5e9",
    "BRAND_RADIUS": "0.5rem",
    "THEME":       "system",
    "ENVIRONMENT": "Staging — data here is not real",  # banner on every page
}

A superuser can change any of these later from the settings screen, without a deploy.

Requirements

Python 3.12+
Django 5.2, 6.0 or 6.1
Runtime dependencies: only Django
Optional integrations (used when installed, never required): django-guardian, django-rules, django-mptt, django-treebeard, django-simple-history

Status: alpha, and I'm being honest about it

The current release is 0.2.0a1. It has more than 4,600 tests, but the API may still change before 1.0. My recommendation: use it on internal tools for now, and pin the exact version.

Try the demo

The repository includes a demo wholesale shop with orders, customers and products. One command migrates it, seeds data and serves it on port 8765:

git clone https://github.com/Pythondeveloper6/django-vantage
cd django-vantage
./example/run.sh

Sign in with admin / admin12345. The demo's example/shop/panel.py is the shortest practical reference for everything in this post.

Links

⭐ GitHub: github.com/Pythondeveloper6/django-vantage
📦 PyPI: pypi.org/project/django-vantage
📖 Docs: pythondeveloper6.github.io/django-vantage

If you try it, I'd really like to hear what Vantage inferred correctly and what it got wrong for your models. Those cases are what improve the inference rules. Issues, ideas and stars on GitHub are all welcome.

Thanks for reading!

Mahmoud Ahmed

Django Context Processor

Mahmoud Ahmed — Mon, 02 Jan 2023 09:57:41 +0000

today we will take about the django context processor
first lets imagine that we are building an Ecommerce Website, so our website will have products where clients can add to the cart then move to the checkout page and complete the process by adding their location and payment information or complete shopping and add more products to the cart

so in every page of the site the client can see the cart with the product that he added before and their quantity and price

so when developing this, we need to include the cart with all of it’s information in every view in our project, and this a really a bad solution, because Django uses DRY concept which means Do Not Repeat Yourself, here the context processor comes to fix this issue,

the context processor is a way to include something in all the site

or what if we want to add the site footer , so the footer we be in all the pages so we need to include it the footer information in all the views or create a context processor for the site footer

so now we should create a context processor for get footer or cart information instead of including that information in all the views in our project, but how can we create a context processor

Creating Context Processor
1 — I will create a new folder in the main project folder with the name of utils I always do this to add all the utils files in this folder (you can name it any name you want) or you can create the file in the app directory

2 — create a new python file with a meaningful name so I will call it settings_context.py for getting footer information then start adding the context processor code in it

so here i imported the footer model then I added a function to get the footer information, it is just a normal Django view that retrieves only one context ‘footer’

in the screenshot I also added another view to get the site logo now we need to include this view in our context processor in our settings.py

3 - so we will open settings.py then move to the templates part then add our context processors for footer and the other for the logo

and if you created a context for cart you will include it also

so now the footer and the logo from our context will be available in all the project templates and we can use it like any context we will include it in {footer.anyinfo} like any template context

now you do not have to include those information in any view

you should use the Django context processor any time you found
yourself need something in all the project pages

if you have any questions leave it below , follow me for more content related to Django , python , data science , machine learning and vuejs

DEV Community: Mahmoud Ahmed

celery-manager: See, Control and Pause Your Celery Tasks Without Touching Your Beat Schedule

celery-manager: See, Control and Pause Your Celery Tasks Without Touching Your Beat Schedule

What you get

How it works: three small parts

Quickstart

1. Install

2. Create the dashboard app

3. Turn on Celery events

4. Run the events listener

5. Create your first user

Going further with @track

Live progress bars

Logs and tracebacks next to the run

The headline feature: pause a schedule without editing it

Full control from the dashboard

Workflows, insights and grouped failures

Plugging it into your stack

Production notes

Status: early alpha

Links

Meet django-vantage: A Django Admin That Configures Itself

Meet django-vantage: A Django Admin That Configures Itself

The idea: smart by default, easy to override

Up and running in 60 seconds

How the "smart" part works

See it, then own it: vantage_scaffold

Overriding only what you care about

A tour of the features

A real data grid

Stats and charts, declared in Python

Kanban, calendar, gallery and map views

Forms with a layout DSL

A cascade-delete preview

Undo that respects your teammates

Permissions, roles and sensitive data

A JSON API for every panel

Theming from one colour

Requirements

Status: alpha, and I'm being honest about it

Try the demo

Links

Django Context Processor

Going further with `@track`

See it, then own it: `vantage_scaffold`