Concepts

Use these concepts to understand how Rippler decides whether a job is healthy. The CLI and API report runs the same way, and you see the same statuses in the app.

Website monitors share the statuses, failure tolerance and uptime below, but not schedules, grace or runs: Rippler checks the site itself. See Website monitors.

Statuses

Status	Meaning
`new`	Created, but has never been pinged or checked.
`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, the job reported a failure, or a website check failed.
`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. Jobs do not finish at the same moment every day, and a backup that usually takes four minutes and occasionally takes nine should not alert. Set it a little above the job's longest normal run time.

Reporting a run

The simplest integration is one call when the job finishes:

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

Pinging /start/ first gives you two things: a duration, and a failure reported when it happens instead of 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 the previous event. For a job that runs every minute and occasionally takes three, the starts and ends interleave and the durations come out wrong. A run id prevents that.

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. A dropped start ping does not turn a successful run into a false alert.

Failure tolerance

alertAfterFailures is how many failures in a row it takes before an alert is sent. 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 alert waits. A success resets the count, so two failures a week apart do not 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. For a website monitor each failed check counts, after its retry.

Uptime

The uptime figure is the share of measured time a monitor spent healthy. up and started count as healthy. down and grace do not.

new and paused are left out of the calculation. A monitor is new from creation until its first ping or check, which is setup time, not downtime. paused is time nobody was watching. A monitor with only unmeasured time shows no percentage instead of 0%.

For the full ping URL shapes and their parameters, see Pings.