Status signals
Decide between named events and exit codes, and see exactly what each signal does to a monitor.
Two ways to tell Drumbeats how a run went. They are equivalent for success and failure:
your_job && curl -sf "$API/success" || curl -sf "$API/failure"your_job && curl -sf "$API/success" || curl -sf "$API/failure"your_job
curl -sf "$API/$?"your_job
curl -sf "$API/$?"Named events cost the same and do more. Exit codes cost the same and take one line. Pick by what the job needs.
Choose one#
| Pick named events when | Pick exit codes when |
|---|---|
You need start, so you get duration tracking and hung-run detection | The whole job is one command and $? is right there |
You want log pings between phases | You want the smallest possible change to the script |
The job is event-driven and needs run_id correlation | The job has one clear success and failure boundary |
| You want to attach stdout or an error message to the finish | You do not need progress, duration, or correlation |
Nothing stops you mixing them. A common shape is start as a named event and the finish as an exit code, which gives you duration tracking with one-line finish handling:
RUN_ID="job-$(uuidgen)"
curl -sf "$API/start?run_id=$RUN_ID"
python worker.py
EXIT=$?
curl -sf "$API/${EXIT}?run_id=$RUN_ID"RUN_ID="job-$(uuidgen)"
curl -sf "$API/start?run_id=$RUN_ID"
python worker.py
EXIT=$?
curl -sf "$API/${EXIT}?run_id=$RUN_ID"What each signal does#
| Signal | Opens a run | Closes a run | Changes monitor status | Can open an incident |
|---|---|---|---|---|
start | yes | no | no | only by timing out later |
success | no | yes | flips UP | no, it resolves them |
failure | no | yes | flips DOWN at failure_tolerance | yes, FAILED |
log | no | no | no | no |
Exit code 0 | no | yes | flips UP | no, it resolves them |
Exit code 1 to 255 | no | yes | flips DOWN at failure_tolerance | yes, FAILED |
Two things follow from this table that surprise people:
A start on its own is not harmless. If no finish arrives inside max_duration_seconds, the run is recorded as hung and counted as a failure. Adding start to a job you do not always finish reporting will create alerts you did not have before.
A log ping is genuinely inert. It cannot resolve an incident, cannot keep a run alive, and cannot flip a monitor. It only costs a beat and leaves a note.
What happens when it breaks#
Incidents come from the finish signal, or the absence of one:
| Trigger | Incident event |
|---|---|
failure, or a non-zero exit code, reaching failure_tolerance | FAILED |
start with no finish inside max_duration_seconds | FAILED |
| No ping at all by the expected time plus the grace period, on Cron and Heartbeat monitors | MISSED |
Finish slower than max_duration_seconds | DURATION_HIGH, a warning |
Finish faster than min_duration_seconds | DURATION_LOW, a warning |
How you get alerted#
Any of the above pages every notification group attached to the monitor, subject to the tolerances in alert logic. Recovery is automatic on the next success or 0.
The URLs#
GET https://api.drumbeats.io/v1/ping/<monitor-id>/start
GET https://api.drumbeats.io/v1/ping/<monitor-id>/success
GET https://api.drumbeats.io/v1/ping/<monitor-id>/failure
GET https://api.drumbeats.io/v1/ping/<monitor-id>/<exit-code>
POST https://api.drumbeats.io/v1/ping/<monitor-id>/logGET https://api.drumbeats.io/v1/ping/<monitor-id>/start
GET https://api.drumbeats.io/v1/ping/<monitor-id>/success
GET https://api.drumbeats.io/v1/ping/<monitor-id>/failure
GET https://api.drumbeats.io/v1/ping/<monitor-id>/<exit-code>
POST https://api.drumbeats.io/v1/ping/<monitor-id>/logGET https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<event>
GET https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<exit-code>GET https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<event>
GET https://api.drumbeats.io/v1/s-ping/<project-id>/<monitor-slug>/<exit-code>Next#
Exit codes for the mapping table and the $? pitfalls. Scheduled pings and event-driven pings for complete patterns. Payloads for attaching context to any of these.