# Monitoring django-celery-beat: Database Schedules, Admin Edits, Alerts

By Dan Ochoa · Published 2026-11-16 · Updated 2026-11-16
Canonical: https://cronradar.com/blog/django-celery-beat-monitoring

> How django-celery-beat stores schedules in PeriodicTask and CrontabSchedule, how admin edits and enabled flags apply, and how to alert on each database task.

**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](https://cronradar.com/blog/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:

```bash
celery -A proj beat -l info --scheduler django_celery_beat.schedulers:DatabaseScheduler
```

Or set `CELERY_BEAT_SCHEDULER = "django_celery_beat.schedulers:DatabaseScheduler"` in Django settings, with the `CELERY_` namespace. The [django-celery-beat docs](https://django-celery-beat.readthedocs.io/en/latest/) describe the models; the behavior below comes from [schedulers.py](https://github.com/celery/django-celery-beat/blob/v2.9.0/django_celery_beat/schedulers.py) and [models.py](https://github.com/celery/django-celery-beat/blob/v2.9.0/django_celery_beat/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()` and `delete()` bump a timestamp in the single-row `PeriodicTasks` table. 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 queryset `update()` doesn't bump the timestamp; beat still reloads everything every 5 minutes.
- **Run state is written back.** `last_run_at` and `total_run_count` are 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_schedule` entry into the database as a `PeriodicTask`. 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:

```python
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`:

```python
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:

```python
# 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)
```

```python
# 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:

```python
# 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 `warning` to `critical` and 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:** `fail` alerts 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 `DISABLED` lines 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](https://docs.cronradar.com/integrations/celery) and [Python SDK guide](https://docs.cronradar.com/integrations/python) cover setup, and [pricing](https://cronradar.com/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.
