Skip to content

Cron Monitoring ​

Did last night's backup run? Is the queue cleanup stuck? Your scheduled jobs report each run to Buggregator, and it shows which runs went fine, which failed, which never started and which never finished. Locally, without a Sentry account.

Available since server 2.13.0.

A job reports in one of two ways:

  • Sentry Crons: the job already uses a Sentry SDK; it sends check-ins to the usual DSN.
  • A ping URL: any script calls curl when it starts and when it ends.

The first report creates the job (a «monitor»). No setup in Buggregator.

TIP

Start Buggregator with a database file (-db buggregator.db or DATABASE_DSN). The default database lives in memory, so jobs and their runs are gone after a restart.

Sentry Crons ​

Point the SDK at Buggregator as usual (Sentry), then use its cron monitoring.

Laravel:

php
$schedule->command('report:nightly')->dailyAt('03:00')->sentryMonitor();

Python:

python
from sentry_sdk.crons import monitor

@monitor(monitor_slug='nightly-report', monitor_config={
    'schedule': {'type': 'crontab', 'value': '0 3 * * *'},
    'timezone': 'Europe/Berlin',
    'checkin_margin': 5,
    'max_runtime': 30,
})
def nightly_report():
    ...

The schedule and limits the SDK sends update the job on every run.

Scripts without an SDK can call Sentry's cron HTTP endpoint the same way:

bash
curl "http://127.0.0.1:8000/api/1/cron/nightly-report/sentry/?status=in_progress"
# {"id":"faa0e9526330486cba530a9cdcc4b28e"}
curl "http://127.0.0.1:8000/api/1/cron/nightly-report/sentry/?status=ok&check_in_id=faa0e9526330486cba530a9cdcc4b28e&duration=2.5"

Ping URL ​

Three addresses per job:

AddressMeans
/ping/<job>/startthe run started
/ping/<job>the run finished fine
/ping/<job>/failthe run failed

GET or POST, no login. A POST body is kept as the run's output (the last 10 KB).

bash
B=http://127.0.0.1:8000
curl -fsS "$B/ping/backup/start?schedule=0+2+*+*+*&tz=Europe/Berlin"
if ./backup.sh > out.log 2>&1; then
  curl -fsS -X POST --data-binary @out.log "$B/ping/backup"
else
  curl -fsS -X POST --data-binary @out.log "$B/ping/backup/fail"
fi

Options in the query:

OptionWhat it sets
schedulecrontab, e.g. 0+2+*+*+* (a + is a space)
tztime zone, e.g. Europe/Berlin; default UTC
marginminutes a run may be late before it counts as missed; default 1
max_runtimeminutes a run may take before it counts as hung; default 30
projectthe project; or the header X-Buggregator-Project
check_in_idwhich run a finish belongs to (the start answers it in the X-Check-In-Id header)
environmente.g. staging

A job name may have letters, digits, ., _ and -, up to 128 characters.

Missed and hung runs ​

Buggregator checks every 30 seconds and adds runs of its own:

StatusWhen
missedthe run was due (schedule + margin) and nothing came. Several missed runs in a row make one entry
timeouta run started and did not finish within max_runtime
unknownthe run was due while Buggregator itself was not running (only with a database file)

The job's own reports are in_progress, ok and error. A job without a schedule is never marked missed.

Schedules: crontab with 5 fields or names like @daily, or an interval from the Sentry SDK (every N minutes, hours, days…). @every and TZ= inside the crontab are not supported.

Where you see it ​

Sentry → Crons lists your jobs: status, schedule, last and next run, and a strip of the last 20 runs. Jobs that failed, hung, missed a run or are running late come first, under Needs attention; a button shows only those. Type in Filter jobs to find one. Times are shown in each job's time zone, and the page updates by itself.

Open a job for its run history: status, start, duration and the output it sent. For a ping job, Ping URLs of this job gives the curl commands to copy. With no jobs yet, the tab shows how to set one up.

Runs make no cards in the event feed. The same data through the API:

RequestGives
GET /api/crons?project=<key>jobs, each with its last 20 runs
GET /api/crons/<job>/checkins?project=<key>the runs of one job, with status, time, duration and output
PUT /api/crons/<job>?project=<key>change the schedule, time zone, margin or max runtime
DELETE /api/crons/<job>?project=<key>delete the job and its runs

A change with PUT lasts until the job sends its own settings again: from its Sentry SDK, or a ping with schedule, tz, margin or max_runtime.

Clearing Sentry data deletes the runs and keeps the jobs with their settings.

Limits ​

  • No alerts: a missed run shows up in Buggregator, nobody is notified.
  • At most 500 jobs per project.
  • A ping sets only a crontab schedule; intervals come from the Sentry SDK.
  • Margin and max runtime are whole minutes. A status may appear up to 30 seconds late.