Concepts

Statuses

Status	Meaning
`new`	Created, but has never been pinged.
`up`	Reporting on schedule.
`started`	A `/start` ping opened a run that has not closed yet.
`grace`	A ping is late, but still inside the grace period.
`down`	Grace ran out, or the job reported a failure.
`paused`	Monitoring is off. No pings expected, no alerts sent.

Schedules and grace

A monitor expects a ping either on a cron expression or at a fixed interval.

Grace duration is how late a ping may be before it counts as missed. It exists because jobs do not finish at exactly the same moment every day — a backup that usually takes four minutes and occasionally takes nine should not page anyone. Set it a little above the job's worst normal run time.

Reporting a run

The simplest thing that works is one call when the job finishes:

curl -fsS -m 10 --retry 5 -o /dev/null https://api.rippler.io/ping/<pingID>/

Opening the run first buys you two things — a duration, and a failure reported the moment it happens rather than when the next ping fails to arrive:

curl … /ping/<pingID>/start/     # before
curl … /ping/<pingID>/           # succeeded
curl … /ping/<pingID>/fail/      # failed

Run ids

Pass ?rid= on both the opening and closing ping to tie them together:

/ping/<pingID>/start/?rid=a1b2c3
/ping/<pingID>/?rid=a1b2c3&duration=12.5

Without one, a closing ping pairs with whatever event came last. For a job that runs every minute and occasionally takes three, the starts and ends interleave and the durations come out wrong. With a run id they cannot.

Duration

?duration= reports the run time in seconds as the job measured it. Prefer it: the server can only see when the pings arrived, which includes network time and any retry backoff.

A /end ping with no matching /start is recorded as a plain success with no duration, rather than being ignored. A dropped start ping should not turn a successful run into a false alert.

Failure tolerance

alertAfterFailures is how many failures in a row it takes before anyone is told. The default is 1 — alert on the first.

Raise it for a job that fails occasionally and recovers on its next run. The monitor still shows as down in the app the whole time; only the notification waits. A success resets the count, so two failures a week apart never add up.

Missed scheduled runs count too: with a tolerance of 3, a daily job that stops running entirely alerts on the third missed day.