Failures, exit codes and start pings
Tell FlatLyne when a job fails, send its exit code and output, and mark when a run starts.
Use this page to make FlatLyne alert you the moment a job fails, instead of waiting for a missed ping. You can send an explicit fail ping, send the job's exit code, attach the job's output, and mark when a run starts.
Send a fail ping
Add /fail to the check's ping URL when your job knows it failed:
curl -fsS -m 10 --retry 5 \
https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI/failWhen FlatLyne receives a fail ping, it:
- Records the ping (shown as FAIL in the check's history).
- Moves the check to Down right away, without waiting for the grace period.
- Sends an alert to the project's alert channels, unless the check was already Down.
Only the fail ping that moves the check to Down sends an alert. More fail pings while it's already Down are recorded in the history but don't alert again. The check stays Down until a success ping arrives. FlatLyne then moves it to Up and sends a recovery alert.
Send the exit code
Instead of choosing between the success URL and /fail yourself, add the job's exit code to the URL. In a shell, $? holds the exit code of the last command:
PING_URL=https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI
0 2 * * * /usr/local/bin/backup-db-nightly.sh; curl -fsS -m 10 --retry 5 "$PING_URL/$?"The first line sets PING_URL, a variable cron passes to the command. FlatLyne treats the code like this:
| Exit code | Counts as | Effect |
|---|---|---|
0 | A success ping | The check moves to Up and gets a new due time. |
| Any other whole number | A fail ping | The check moves to Down and FlatLyne sends an alert. |
| Not a number | Nothing | FlatLyne returns 400 invalid exit code and records nothing. |
FlatLyne stores the exit code with the ping.
Choose ; or &&
The character between your command and curl decides whether FlatLyne hears about failures.
PING_URL=https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI
0 2 * * * /usr/local/bin/backup-db-nightly.sh; curl -fsS -m 10 --retry 5 "$PING_URL/$?"With ;, curl runs whether the job succeeds or fails, and $? carries the result. A failed run marks the check Down right away.
Use ; with $? when you want to hear about failures as soon as they happen.
Catch failures inside pipelines
In a pipeline such as pg_dump | gzip, $? is the exit code of the last command only. If pg_dump fails but gzip succeeds, the pipeline exits with 0 and FlatLyne records a success.
Turn on pipefail in your script so the pipeline fails when any command in it fails:
#!/usr/bin/env bash
set -o pipefail
pg_dump app_production | gzip > /var/backups/app_production.sql.gz
curl -fsS -m 10 --retry 5 \
"https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI/$?"pipefail is a bash option. It doesn't exist in every /bin/sh, so start the script with #!/usr/bin/env bash.
Send the job's output
FlatLyne stores the request body of each ping, up to 10 KB (10,240 bytes). Send your job's output in the body and you can read it in the dashboard: open the check's page, select the ping in its history, and look under Body.
If the body is longer than 10 KB, FlatLyne keeps the first 10 KB and still records the ping. Errors usually show up at the end of the output, so send the last 10 KB:
#!/usr/bin/env bash
PING_URL="https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI"
output=$(/usr/local/bin/backup-db-nightly.sh 2>&1)
code=$?
printf '%s' "$output" | tail -c 10240 \
| curl -fsS -m 10 --retry 5 --data-binary @- "$PING_URL/$code"This captures standard output and standard error, saves the exit code before anything else can change $?, and posts the tail of the output to the exit-code URL. --data-binary @- reads the body from standard input and sends it as is, line breaks included.
For short output, --data-raw works too:
curl -fsS -m 10 --retry 5 --data-raw "rotated 14 log files" \
https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NIStart pings
Add /start to the ping URL when your job begins:
#!/usr/bin/env bash
PING_URL="https://api.flatlyne.com/CSps9LOZGccsl2o7ieL0_YrQyZJtkGK_0H1u30FJ-NI"
curl -fsS -m 10 --retry 5 "$PING_URL/start"
/usr/local/bin/backup-db-nightly.sh
curl -fsS -m 10 --retry 5 "$PING_URL/$?"A start ping:
- Is recorded in the check's history as STARTED.
- Doesn't change the check's state. An Up check stays Up, a Down check stays Down.
- Doesn't change the check's due time. If the job starts and then hangs or gets killed before its final ping, the check still goes Grace and then Down on schedule, and you get the alert.
To see how long a run took, open the check's page. Each ping in the history shows the time since the previous ping, so the success or fail ping that follows a start ping shows the length of that run. FlatLyne doesn't give runs an ID. If two runs of the same check overlap, their pings mix together in the history.
A start ping counts toward the check's limit of 3 pings per minute, so a run that sends a start ping and a final ping uses 2 of them.