Skip to content
bucker

Cron monitoring

A cron monitor tells you when a scheduled job did not run, ran and failed, or started and never finished. The job reports in with check-ins; Bucker watches the clock. Every failure becomes an ordinary issue, with the same short id, assignment and alert routing as a crash.

There are four ways to send check-ins. They all land on the same service, so the same rules hold: a check-in with a schedule creates the monitor on first sight and keeps its schedule current after that.

You have Use
A Node job withMonitor from @bucker/node
node-cron tasks, BullMQ repeatable jobs instrumentNodeCron, instrumentBullMQ (automatic, below)
Celery beat tasks install(app, monitor_beat_tasks=True) (automatic, below)
A Python job with_monitor from bucker-sdk
Any command (shell, Go, Ruby, a binary) bucker-cron run
A crontab line and nothing else the heartbeat URL

Node

import { withMonitor, flush } from '@bucker/node'

await withMonitor(
  'nightly-export',
  () => exportEverything(),
  { schedule: { type: 'crontab', value: '0 2 * * *' }, checkinMargin: 5, maxRuntime: 30 },
)
await flush() // a job that exits right away must flush, or its last check-in is a false "missed"

withMonitor sends in_progress, then ok (or error if the callback throws; the error still propagates), under one check-in id and with the run's duration.

node-cron and BullMQ, without wrapping each job

import cron from 'node-cron'
import { instrumentNodeCron } from '@bucker/node/integrations/crons'

instrumentNodeCron(cron).schedule('0 2 * * *', nightlyExport, { name: 'nightly-export' })

instrumentNodeCron wraps schedule(): a task with a name option is bracketed like withMonitor and its crontab becomes the monitor's schedule. instrumentBullMQ(bullmq) returns the module with a Worker that does the same for jobs made by a repeat rule (pattern, every, upsertJobScheduler). Neither library is a dependency of the SDK. Details and limits are in the Node SDK.

Python

from bucker_sdk import with_monitor

@with_monitor("nightly-export", monitor_config={
    "schedule": {"type": "crontab", "value": "0 2 * * *"},
    "checkin_margin": 5, "max_runtime": 30, "timezone": "UTC",
})
def nightly_export(): ...

It is also a context manager (with with_monitor("one-off"): ...).

For Celery beat, bucker_sdk.celery.install(app, monitor_beat_tasks=True) brackets every task in beat_schedule with check-ins and derives the monitor schedule from the entry (a crontab, or an interval of a minute or more). See the Python SDK.

Any command: bucker-cron

@bucker/node ships a zero-dependency wrapper. It needs only Node 20 and a DSN:

export BUCKER_DSN="https://<public-key>@us.ingest.bucker.io/<project-id>"

# in your crontab, around the command you already run
0 2 * * * npx -y -p @bucker/node bucker-cron run nightly-backup --schedule "0 2 * * *" -- /opt/backup.sh --full

It sends in_progress, runs the command with its output untouched, then sends ok or error with the duration, and exits with the command's own exit code. If Bucker is unreachable it prints a warning and the command is unaffected: the monitor never becomes the outage.

Option Meaning
--dsn The project DSN (default $BUCKER_DSN)
--schedule "<cron>" Cron expression. Creates or updates the monitor
--interval-minutes <n> Expect a run every n minutes instead
--timezone <iana> Timezone for --schedule (default UTC)
--grace <minutes> Lateness tolerated before a run counts as missed
--max-runtime <minutes> How long an in-progress run may last before it times out
--environment <name> Environment tag

Without --schedule or --interval-minutes the monitor must already exist. A command that cannot start exits 127 and is reported as a failed run.

Plain HTTP

# the whole integration, in a crontab
0 2 * * * /opt/backup.sh && curl -fsS "https://us.ingest.bucker.io/api/<project-id>/monitors/nightly-backup/heartbeat?sentry_key=<public-key>"

POST /api/<project-id>/monitors/<slug>/checkins takes { status, checkInId?, durationMs?, environment?, monitorConfig? }; PUT .../checkins/<checkInId> closes a run. status is in_progress, ok or error. The heartbeat URL means "I just completed" (&status=error reports a failure).

The config in a check-in is an upsert

When a check-in carries a schedule (monitor_config in the SDKs, monitorConfig over HTTP) the monitor is created if it does not exist and updated if it does: the job's code is where the schedule is written down, so a changed crontab in your deploy reaches the monitor on the next ping instead of leaving it expecting the old time.

What an upsert changes: the schedule (cron expression or interval, timezone), and the grace period and max runtime when the config states them. A config that changes nothing writes nothing.

What it never changes: the monitor's name, whether it is enabled (a paused monitor stays paused), its owner, its thresholds and its mute. Those belong to people, in the console.

New monitors from a check-in are held to the console's rules: slugs are lowercase letters, digits, - and _ (up to 64), and a project has a ceiling on how many monitors it can hold.

What alerts, and when

A monitor opens an issue for a failed run (error), a missed run (nothing arrived within the grace period after the expected time) and a timeout (started, never finished within the max runtime). Each kind is its own issue. A successful run resolves them.

Three policy fields keep a flaky job from paging you, and tell Bucker who to tell:

  • Failure threshold (default 1): consecutive failed runs before an issue opens. One flaky run does not page when you set 2 or 3.
  • Recovery threshold (default 1): consecutive successful runs before the issue resolves.
  • Owner: a person or a team. An alert rule with a notify_owner action routes a monitor's issue to the owner you set here, and says so in the message.
  • Mute: silence a monitor until a time, up to 30 days. A muted monitor still records runs and opens issues; its alerts are written to the alert history as suppressed, naming the mute, so nothing is silently lost. Muting is never billed differently and never deactivates the monitor.

Set them on the monitor in the console, or PATCH the monitor (failureThreshold, recoveryThreshold, ownerPrincipalId, ownerTeamId, mutedUntil). Planned downtime is better expressed as a maintenance window, which silences everything it covers.

Changing a monitor from an agent

A person edits a monitor in the console or with PATCH …/monitors/:slug, directly. An agent, a service or an OAuth client changes one only through the governed cron_monitor operation, and the act is read from the before-and-after diff, never named by the caller. The tool is monitors_update (and PATCH for a non-person, which takes reason, minutes and approvalRequestId); monitors_create is unchanged and still asks for every monitor before it exists.

The diff Act Decision
a rename, an owner change, or a schedule rewrite that keeps the number of ticks a week monitor.update asks; an organization's ALLOW row conditioned on direction: neutral applies it
a shorter grace period or maximum runtime, a lower failure threshold, a denser schedule monitor.update asks (it fires more, so it never rides a neutral-only row)
a longer grace period or maximum runtime, a higher failure threshold, a sparser schedule, another environment, a cleared owner monitor.narrow ask floor, an end time (minutes, at most 7 days for an agent), the earlier values come back at the end, CRITICAL when the monitor backs a status component
muted: true with minutes monitor.mute asks; CRITICAL when the project pages a person and the mute is longer than 4 hours; at most 7 days for an agent, 30 for a person
enabled: false with minutes monitor.disable asks with an end; CRITICAL when the monitor backs a status component
muted: false / enabled: true monitor.unmute / monitor.enable applied (ELEVATED): they restore alerting

Fires less is read from the cadence, not the text. A schedule change is compared by the ticks it expects in a week, so 0 2 * * * to 0 3 * * * (or to another time zone) is neutral, daily to weekly is a silence, and an interval of 60 minutes to 120 is a silence. A silence has an end: a mute, a disable or a narrowing states minutes, and when they run out the monitor is un-muted, re-enabled or restored to its stored values, even if a person has edited it since. An agent states a length rather than an end time (mutedUntil is refused for it) because a plan is made again on the retry and must come out the same.

One kind of change a call: a patch of fields, or a mute, or an enable or disable. A patch that both tightens and loosens is refused: the inverse of a mixed change would undo the half you meant to keep. An approval is bound to the monitor's revision; a dashboard edit between the yes and the retry closes it TARGET_CHANGED. Every approved change leaves a signed receipt, and monitor.mute, monitor.unmute, monitor.disable, monitor.enable and monitor.narrow audit rows carrying the operation and approval ids.

checks_list with include: ["cron"] lists each cron monitor with its schedule, last check-in, status, owner, mute (an expired mute reads as none) and the number of its open issues, so an agent sees what it is about to change.

The sweeps report on themselves

The miss and timeout sweeps are evaluators of the checks family: each pass writes a row per organization it handled (what was due, what was evaluated, what failed). A monitor whose handling throws is counted on its organization's row and the sweep goes on to the next; a pass in which every monitor failed is a failed pass in the scheduler console, instead of a green one that checked nothing.

Sentry compatibility

An unmodified Sentry SDK's captureCheckIn and withMonitor already work: pointed at a Bucker DSN they arrive as check_in envelope items and go through the same service, including the upsert. Monthly and yearly intervals have no fixed length in minutes and are refused rather than guessed.