checkpulse-run

checkpulse-run wraps a job so it reports to Checkpulse without any changes to the job itself. It:

1. sends /start with a new run ID,
2. runs the command, passing its output through,
3. sends the exit status with the command line, duration, and the last 4 KB of output,
4. exits with the command's own exit status.

If a ping fails, the wrapper prints a warning on stderr and retries, but never changes the job's exit status.

Install

The shell version needs only sh and curl:

curl -fsSL https://checkpulse.foo/checkpulse-run.sh -o /usr/local/bin/checkpulse-run
chmod +x /usr/local/bin/checkpulse-run

Review the script before installing it; it is short.

Use

checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh --full

Or set the URL in the environment:

CHECKPULSE_URL='https://checkpulse.foo/ping/<token>' checkpulse-run /usr/local/bin/backup.sh

The shell version merges the job's stderr into its stdout.

In crontab

0 2 * * * /usr/local/bin/checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh

With systemd timers

[Service]
Type=oneshot
ExecStart=/usr/local/bin/checkpulse-run 'https://checkpulse.foo/ping/<token>' /usr/local/bin/backup.sh

Slug URLs and automatic creation

Combine with slug URLs to monitor a job without creating the check first:

checkpulse-run "https://checkpulse.foo/ping/$PING_KEY/nightly-backup" /usr/local/bin/backup.sh

Set CHECKPULSE_CREATE=1 to create the check on its first ping, with a daily schedule you can adjust later.

The checkpulse binary

The checkpulse server binary includes the same wrapper as a subcommand, and is in the Checkpulse Docker image:

checkpulse run --url 'https://checkpulse.foo/ping/<token>' -- /usr/local/bin/backup.sh --full
checkpulse run --server https://checkpulse.foo --ping-key "$PING_KEY" --slug nightly-backup --create -- ./backup.sh

The binary keeps stdout and stderr separate. A command that cannot be found exits with 127 and reports a failure.

View as Markdown