Drumbeats logo
Drumbeats
Reference

Monitoring Modes

Drumbeats has two monitoring modes — scheduled (cron / heartbeat) for predictable timetables and event-driven for jobs that run on demand.

Drumbeats has two monitoring modes that cover almost every background-job shape: scheduled (predictable timetable — cron and heartbeat) and event-driven (on-demand — queue workers, webhook handlers, CI jobs). Pick scheduled when Drumbeats should detect a late or missed run automatically. Pick event-driven when runs are unpredictable but you still care about duration and explicit success / failure.

For the per-type picker with examples see Monitor types; for the HTTP patterns each mode uses see Ping API.

Scheduled jobs

Best for nightly backups, weekly reports, hourly syncs, ETL windows — anything with a deterministic schedule.

  • You configure — a cron schedule (or a Heartbeat interval like 5m, 1h) plus a grace period.
  • Drumbeats expects — a success ping by expected_time + grace_period_seconds. Optionally a start ping too, for duration tracking.
  • Drumbeats alerts on — a missed window (no ping by expected_time + grace_period) or an explicit failure ping.

How to configure a scheduled monitor

  1. Choose Cron or Heartbeat when creating the monitor.
  2. Enter the cron expression (0 0 * for midnight daily) or the interval (5m).
  3. Set a grace period (grace_period_seconds) — the buffer Drumbeats waits past expected_time before declaring the run missed. Default 300 seconds.
  4. Send success (and failure if needed) when the job ends.

Example — nightly backup

bash
# Cron entry: 0 0 * * *
/usr/bin/backup.sh \
  && curl https://api.drumbeats.io/v1/ping/<monitor-id>/success \
  || curl https://api.drumbeats.io/v1/ping/<monitor-id>/failure
# Cron entry: 0 0 * * *
/usr/bin/backup.sh \
  && curl https://api.drumbeats.io/v1/ping/<monitor-id>/success \
  || curl https://api.drumbeats.io/v1/ping/<monitor-id>/failure

See Scheduled pings for the recommended start + success/failure shape and progress-log patterns.

Event-driven jobs

Best for queue workers, CI pipelines, user-triggered tasks, webhook handlers, data imports — anything that runs on demand rather than on a clock.

  • You configure — a max_duration_seconds ceiling that represents "this job should finish by …".
  • Drumbeats expects — a start ping with a unique run_id at the top, then success or failure with the same run_id at the end.
  • Drumbeats alerts on — a start that never finishes (hung run, treated as failure) or an explicit failure ping.

How to configure an event-driven monitor

  1. Choose Event-driven when creating the monitor.
  2. Set max_duration_seconds to your tolerable upper bound.
  3. Send start with a unique run_id, then success or failure with the same run_id.

Example — queue worker

bash
RUN_ID="job-$(date +%s)-$$"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
node process-message.js
EXIT=$?
if [ $EXIT -eq 0 ]; then
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/success?run_id=$RUN_ID"
else
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/failure?run_id=$RUN_ID"
fi
RUN_ID="job-$(date +%s)-$$"
curl "https://api.drumbeats.io/v1/ping/<monitor-id>/start?run_id=$RUN_ID"
node process-message.js
EXIT=$?
if [ $EXIT -eq 0 ]; then
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/success?run_id=$RUN_ID"
else
  curl "https://api.drumbeats.io/v1/ping/<monitor-id>/failure?run_id=$RUN_ID"
fi

See Event-driven pings for run_id strategies and language-specific examples in Node.js, Python, Go, and PHP.

Picking the right mode

  • Choose scheduled when you know exactly when runs should happen — Drumbeats does the missed-window detection for you.
  • Choose event-driven when runs are unpredictable but you still want duration tracking and concurrency-safe correlation via run_id.
  • Mix both freely — each monitor is independent. A typical project has cron monitors for nightly tasks and event-driven monitors for the queue workers.