Monitoring django-celery-beat: Database Schedules, Admin Edits, Alerts
Contents
With django-celery-beat, the schedule is rows in your database: each PeriodicTask points at one CrontabSchedule, IntervalSchedule, SolarSchedule, or ClockedSchedule, and beat runs only the rows that are enabled. Anyone with admin access can add, change, or disable a task without a deploy, so monitoring has to follow the database, not your code. cronradar-celery discovers only app.conf.beat_schedule, so tasks that exist only in the database need to report explicitly, with a monitor key and schedule per task.
This guide covers django-celery-beat 2.9.0 with Celery 5, checked November 16, 2026. For a task that doesn't run at all, start with Celery beat not running, which covers the wrong scheduler, the 7-for-Sunday trap, and bulk updates beat doesn't see. This post goes further into how the database scheduler works and how to monitor what's in it.
How the DatabaseScheduler Reads the Schedule#
Beat uses the database only when you tell it to, with -S django or the full path:
celery -A proj beat -l info --scheduler django_celery_beat.schedulers:DatabaseSchedulerOr set CELERY_BEAT_SCHEDULER = "django_celery_beat.schedulers:DatabaseScheduler" in Django settings, with the CELERY_ namespace. The django-celery-beat docs describe the models; the behavior below comes from schedulers.py and models.py.
- Only enabled rows are loaded. Beat builds its in-memory schedule from
PeriodicTask.objects.enabled(). - Changes are detected through one row.
PeriodicTask.save()anddelete()bump a timestamp in the single-rowPeriodicTaskstable. Beat checks it each tick and reloads when it's newer. Beat's maximum sleep with this scheduler is 5 seconds, so an admin edit is usually live within seconds. A querysetupdate()doesn't bump the timestamp; beat still reloads everything every 5 minutes. - Run state is written back.
last_run_atandtotal_run_countare updated in memory when beat sends a task and saved to the row when beat syncs, including at shutdown. - Your code's schedule is merged in. At startup, the scheduler upserts every
app.conf.beat_scheduleentry into the database as aPeriodicTask. A code-defined entry deleted in the admin comes back the next time beat starts.
That last point means a database-scheduled project usually has two kinds of rows: ones that came from code and are recreated on every start, and ones that were created in the admin or by application code and exist nowhere else.
The Models and Fields That Decide Whether a Task Runs#
A PeriodicTask must have exactly one schedule. Model validation rejects zero or more than one, and a clocked schedule requires one_off=True.
| Schedule model | Fields | Use |
|---|---|---|
CrontabSchedule |
minute, hour, day_of_month, month_of_year, day_of_week, timezone |
Calendar times |
IntervalSchedule |
every, period (DAYS, HOURS, MINUTES, SECONDS, MICROSECONDS) |
A fixed gap since the last run |
SolarSchedule |
event, latitude, longitude |
Sunrise, sunset, and similar |
ClockedSchedule |
clocked_time |
One run at a specific time |
On the PeriodicTask itself:
| Field | Effect |
|---|---|
name |
Unique label for the row; one Celery task can have many rows with different arguments |
task |
The registered Celery task name, such as reports.tasks.export_report |
args, kwargs |
JSON passed to the task |
queue, exchange, routing_key, priority, headers |
Routing for the message beat sends |
enabled |
Off means beat doesn't load the row at all |
one_off |
After one run, beat sets enabled to False |
start_time |
Beat holds the task until this time |
expires or expire_seconds |
expires is a datetime; once it passes, beat disables the row. You can't set both |
last_run_at, total_run_count |
Written by beat; useful for checking that a row is running |
Two consequences for monitoring. A row turned off by one_off or expires disables itself silently; nothing logs it as an error. And because enabled is a checkbox in the admin, the most common way a scheduled task stops is someone turning it off, on purpose or not.
Time Zones Are Per Crontab Row#
Each CrontabSchedule has its own timezone, defaulting to the Celery timezone setting (CELERY_TIMEZONE in Django settings) and falling back to UTC, not Django's TIME_ZONE. Two crontab rows with the same fields and different zones run at different times, and the admin shows both as "0 6 * * *". DJANGO_CELERY_BEAT_TZ_AWARE, True by default, makes beat compare times in the app's time zone.
If you change the Celery time zone, existing rows don't follow. The docs' fix resets every task's last run so beat treats each as never run:
from django_celery_beat.models import PeriodicTask, PeriodicTasks
PeriodicTask.objects.update(last_run_at=None)
PeriodicTasks.update_changed()List What's Actually Scheduled#
Beat has no command that prints its schedule, and celery inspect scheduled shows tasks waiting on an ETA in workers, not beat's entries. The database is the source of truth, so query it. Save this as a management command, reports/management/commands/list_beat_tasks.py:
from django.core.management.base import BaseCommand
from django_celery_beat.models import PeriodicTask
def describe(task):
if task.crontab:
c = task.crontab
return f"crontab {c.minute} {c.hour} {c.day_of_month} {c.month_of_year} {c.day_of_week} ({c.timezone})"
if task.interval:
return f"every {task.interval.every} {task.interval.period}"
if task.solar:
return f"solar {task.solar.event}"
if task.clocked:
return f"once at {task.clocked.clocked_time:%Y-%m-%d %H:%M %Z}"
return "no schedule"
class Command(BaseCommand):
help = "List every django-celery-beat periodic task and its state."
def handle(self, *args, **options):
tasks = PeriodicTask.objects.select_related("crontab", "interval", "solar", "clocked").order_by("name")
for task in tasks:
state = "enabled" if task.enabled else "DISABLED"
flags = []
if task.one_off:
flags.append("one_off")
if task.expires:
flags.append(f"expires {task.expires:%Y-%m-%d %H:%M}")
if task.start_time:
flags.append(f"starts {task.start_time:%Y-%m-%d %H:%M}")
last = f"{task.last_run_at:%Y-%m-%d %H:%M}" if task.last_run_at else "never"
self.stdout.write(
f"{state:8} {task.name!r} -> {task.task} | {describe(task)} | "
f"last run {last}, {task.total_run_count} runs {' '.join(flags)}"
)Run it with python manage.py list_beat_tasks in each environment and compare. Rows marked DISABLED that should be running, enabled rows with last run never, and a last_run_at far older than the schedule are the three things to look for. Remember that last_run_at records when beat sent the task, not whether a worker finished it.
Why Code-Based Monitoring Misses Database Tasks#
cronradar-celery 0.1.1 discovers schedules from app.conf.beat_schedule when setup_cronradar(app) runs, translates each entry to five-field cron, and reports each run from Celery's task_prerun, task_success, and task_failure signals. Under the database scheduler, entries you define in code are still discovered, because they're in beat_schedule before beat copies them into the database.
It does not read django-celery-beat's tables. A task created in the admin is never declared to CronRadar, so CronRadar has no schedule to expect it on, and a missed run can't alert. Its signal handlers report runs under a key built from the Celery task name, without a schedule, so they can't create a monitor for a database task either. And one Celery task scheduled by several PeriodicTask rows with different arguments would share one key.
Database tasks need their own reporting: one monitor per PeriodicTask row, keyed on something stable, with the row's schedule.
Report Each Database Task From Inside the Task#
The task needs to know which row sent it. The simplest reliable way is to put the row's name in its kwargs, for example {"report_id": 7, "periodic_task": "Export report 7"} in the admin, and look the row up when the task runs. The lookup reads the current crontab, so the schedule you report follows admin edits:
# reports/monitoring.py
import logging
from contextlib import nullcontext
import cronradar
from django.utils.text import slugify
from django_celery_beat.models import PeriodicTask
log = logging.getLogger(__name__)
def monitor_for(periodic_task_name):
"""Return (key, schedule) for a crontab PeriodicTask, or None."""
try:
task = PeriodicTask.objects.select_related("crontab").get(name=periodic_task_name)
except Exception as error:
log.warning("No monitor for %r (%s)", periodic_task_name, type(error).__name__)
return None
if task.crontab is None:
return None
c = task.crontab
schedule = f"{c.minute} {c.hour} {c.day_of_month} {c.month_of_year} {c.day_of_week}"
return f"beat-{slugify(task.name)}"[:100], schedule
def monitored(periodic_task_name):
"""Report start, completion, or failure for this row. Never raises on its own."""
monitor = monitor_for(periodic_task_name) if periodic_task_name else None
if monitor is None:
return nullcontext()
key, schedule = monitor
return cronradar.job(key, schedule=schedule)# reports/tasks.py
from celery import shared_task
from reports.exports import run_export
from reports.monitoring import monitored
@shared_task
def export_report(report_id, periodic_task=None):
with monitored(periodic_task):
return run_export(report_id)cronradar.job from the cronradar Python SDK (0.1.1) sends a start when the block begins, a completion when it ends, and a failure with the exception message if it raises, then re-raises the exception so Celery records the failure and retries as usual. Its requests time out after five seconds and never raise into the task. Set CRONRADAR_API_KEY in the worker's environment.
If you also run cronradar-celery, put @skip_monitor under the task decorator (@shared_task first, then @skip_monitor), so its signal handlers don't report the same run under the task-name key as well.
Check the reported schedule against two rules. CronRadar accepts five-field cron in the application's time zone, set in its settings (UTC if unset), so every crontab row you monitor through one CronRadar application should use that zone; put rows in another zone in a separate application. And use 0 for Sunday, never 7. Interval, solar, and clocked rows return None above and run unmonitored; an interval that divides an hour evenly can usually be rewritten as a crontab.
Declare Database Tasks Ahead of Their First Run#
The in-task check-in has two gaps. A new row isn't monitored until it runs once, so a task that never runs is never expected. And the schedule on a check-in applies only when it creates the monitor, so an admin edit to the crontab doesn't move the expected time.
Both are closed by declaring the rows to CronRadar's registry sync endpoint, POST /sync, which creates monitors before their first run, updates a schedule when the declared value changes, and, with mode: "reconcile", pauses monitors for rows that were disabled or deleted, keeping their history. This command sends every enabled crontab row with the same keys as above:
# reports/management/commands/sync_beat_monitors.py
import base64
import json
import os
import urllib.request
from django.core.management.base import BaseCommand
from django_celery_beat.models import PeriodicTask
from reports.monitoring import monitor_for
class Command(BaseCommand):
help = "Declare enabled django-celery-beat crontab tasks to CronRadar."
def handle(self, *args, **options):
monitors = []
for task in PeriodicTask.objects.filter(enabled=True, crontab__isnull=False):
if '"periodic_task"' not in (task.kwargs or ""):
continue # Only rows whose task reports with monitored().
monitor = monitor_for(task.name)
if monitor is None:
continue
key, schedule = monitor
monitors.append({"key": key, "name": task.name, "schedule": schedule, "gracePeriod": 600})
body = json.dumps({
"source": "django-celery-beat",
"mode": "reconcile",
"monitors": monitors,
}).encode()
token = base64.b64encode(f"{os.environ['CRONRADAR_API_KEY']}:".encode()).decode()
request = urllib.request.Request(
"https://cron.life/api/v1/sync", data=body, method="POST",
headers={"Content-Type": "application/json"},
)
request.add_unredirected_header("Authorization", f"Basic {token}")
with urllib.request.urlopen(request, timeout=5) as response:
result = json.load(response)
self.stdout.write(json.dumps(result["summary"]))
for error in result.get("errors", []):
self.stderr.write(json.dumps(error))Run it after deploys and on a schedule of its own, such as a cron entry every 15 minutes, so admin edits reach CronRadar promptly. Don't run it more than 10 times a minute. Because it's reconcile mode for its own source, it never touches monitors created by cronradar-celery or other integrations, and an empty list pauses every monitor it declared before, so don't run it against the wrong database.
What Gets Caught, and What Doesn't#
With rows declared and tasks reporting:
- Beat or the workers stop: no start arrives. After the expected time plus the grace period, the monitor goes from
warningtocriticaland alerts by email, Slack, webhook, Discord, or PagerDuty. A monitor declared before its first run that never reports gets a NeverExecuted alert instead. - The task raises:
failalerts immediately, once per failed attempt if the task retries. - A worker dies mid-run: a start with no finish is flagged as stuck.
- Someone disables a row: the next sync pauses its monitor. That's deliberate: a disabled task isn't expected to run. If disabling tasks by accident is your risk, review the paused monitors, or the
DISABLEDlines from the listing command, as part of your routine. - A one-off or expired row turns itself off: same as disabled.
Neither part sees a task that isn't wired up: a row whose kwargs lack periodic_task, or a task that doesn't use monitored(). The listing command is how you find those. Use a separate CronRadar application and key per environment; the Celery integration guide and Python SDK guide cover setup, and pricing covers monitor counts.
Frequently Asked Questions#
How do I see which tasks django-celery-beat will run?#
Query the PeriodicTask table: every enabled row with a schedule is what beat loads. The admin's Periodic Tasks page shows the same data, but a management command like the one above lets you see enabled, one_off, expires, the crontab's time zone, and last_run_at for every row at once, in every environment.
Why did my django-celery-beat task disable itself?#
Either one_off was set and the task ran once, or expires passed. In both cases beat sets enabled to False and saves the row without an error. Moving expires later doesn't revive it; re-enable the row as well.
How long does an admin change take to reach beat?#
Usually a few seconds. Saving a row through the admin or the model's save() bumps the PeriodicTasks timestamp, and the database scheduler checks it on each tick, sleeping at most 5 seconds. Bulk changes with update() don't bump it, so call PeriodicTasks.update_changed() after them, or wait for the 5-minute full reload.
Does cronradar-celery monitor django-celery-beat tasks?#
Only the ones defined in app.conf.beat_schedule, which it discovers in code before beat copies them into the database. Tasks created only in the admin or the database aren't discovered. Report those from inside the task with cronradar.job and a monitor key and schedule per row, or with HTTP check-ins, and declare them with the sync endpoint so missed runs alert.
Do I need a separate monitor for each PeriodicTask row?#
Yes, if each row is a separate job you'd want to hear about. Several rows can call the same Celery task with different arguments and schedules, and each has its own expected times. Keying the monitor on the row's unique name gives each its own schedule and alert.
Put this guide to work
Connect your Python job to monitoring
Follow the current integration guide, check the release limitations, and verify a real run and alert delivery.
PyPI installs cronradar 0.1.2. It reports the jobs you wrap and does not discover jobs automatically.