Cron monitors
Know when a scheduled job misses its time, fails or runs too long. Check in from curl or the Node SDK, on Vercel, Fly or any server, and get an alert.
A cron monitor watches one scheduled job: a backup, a report, a queue drain. The job checks in when it starts and when it ends, with one HTTP request from curl or one call from the Node SDK. Little Friend knows when each run is due, so it notices the run that never came as well as the one that failed or ran too long. The Crons page shows each job's runs and durations, and a cron alert emails your team or posts to Slack when a job misses its schedule or fails.
Add a monitor
Open Crons in the dashboard and add the job, or let the job create its own monitor on its first check-in (see below). A project can have up to 50 monitors. Editors and owners add, change, pause and delete them; everyone in the workspace, and read keys, can see them.
- Slug, the name the job checks in with: lowercase letters, digits,
-and_, starting with a letter or digit, up to 64 characters. It stays as created. - Name, up to 80 characters, shown in the dashboard and in alerts. The slug when you leave it out.
- Schedule: a cron expression read in a time zone, or an interval. See Schedules.
- Check-in margin: how many minutes a run may start after its time before that time counts as missed. 1 to 1,440, 5 by default.
- Max runtime: how many minutes a started run may take before it counts as timed out, which is a failure. 1 to 1,440, 30 by default.
- Paused: a paused monitor expects nothing and fires no alert.
Creating a monitor shows its ping URL once, and offers to create its two alerts. Or from the terminal, with the Little Friend CLI, where --alert creates both:
littlefriend crons create nightly-backup --schedule "0 3 * * *" \
--timezone Europe/Paris --margin 10 --max-runtime 60 --alert
littlefriend crons create queue-drain --every 15m
littlefriend crons list
littlefriend crons update nightly-backup --max-runtime 90
littlefriend crons history nightly-backup --failed
littlefriend crons ping-url nightly-backup --yes
littlefriend crons delete queue-drain --yesA monitor is named by its id (crm_...) or its slug. See the CLI reference for every flag.
Schedules
A cron expression has five fields: minute, hour, day of month, month and day of week, such as 0 3 * * * for 03:00 every day or */15 * * * * for every quarter hour. Ranges, lists, steps and the names of months and days work, and so do the macros @hourly, @daily, @weekly, @monthly and @yearly. When both day fields are restricted, a day that matches either one runs, as cron does.
The expression is read in an IANA time zone, such as Europe/Paris, UTC by default, and follows its daylight saving changes:
- A time the clocks skip, such as 02:30 on a spring-forward night, runs once, when the clocks jump.
- A time the clocks repeat runs once, at its first reading, unless the expression runs every hour, in which case it keeps running through the repeated hour.
An interval, such as every 6 hours, has a unit of minute, hour, day or week, and counts from the start of each run, not from the clock. Use one for a job whose host picks its own time, such as a Fly scheduled Machine.
A run may start up to 60 seconds early and still count for its time, so a clock a little fast is fine.
Check in
Check-ins go to the collector as a POST, in one of two ways. Both work from plain curl, with no SDK.
- With the project's secret server key (
lfs_), the one server errors use, as a bearer token:https://in.littlefriend.io/v1/crons/<slug> - With the monitor's ping URL, and no header:
https://in.littlefriend.io/v1/crons/ping/<token>. The URL holds its own secret, shown once when the monitor is created or when you make a new one. Making a new one stops the old one. A monitor that a check-in created has none until you make one.
The simplest check-in is a bare POST once the job has done its work. It counts as a run that went well:
curl -fsS -m 10 --retry 3 -X POST https://in.littlefriend.io/v1/crons/nightly-backup \
-H "Authorization: Bearer $LF_SERVER_KEY"A check-in can carry these fields, in the query, in a form body (curl -d) or in a JSON body. A field in the body wins over the same field in the query.
status:in_progress(orstart),ok,error.okwhen it is left out, so a bare POST is a run that went well.check_in_id: Links a finish to its start: up to 64 letters, digits,-and_. Choose one yourself, or use the one the start answers with. A finish without one closes the latest run still going.duration_ms: How long the run took. After a start, it defaults to the time since that start.message: Why a run failed. Kept onerroronly, scrubbed like an error message, at most 200 characters.monitor: JSON body only: the monitor itself, so code declares its own schedule. See below.
To catch a job that hangs or dies, check in when it starts and again when it ends. This script reports the error when any command fails, and its finish needs no duration, since the start marked the time:
#!/usr/bin/env bash
# nightly-backup.sh: checks in when it starts, and again when it ends, however it ends.
set -euo pipefail
URL="https://in.littlefriend.io/v1/crons/nightly-backup"
ID="run-$(date +%s)-$$"
checkin() {
curl -fsS -m 10 --retry 3 -o /dev/null "$URL" \
-H "Authorization: Bearer $LF_SERVER_KEY" -d check_in_id="$ID" "$@" || true
}
finish() {
code=$?
if [ "$code" -eq 0 ]; then
checkin -d status=ok
else
checkin -d status=error --data-urlencode "message=exited with $code"
fi
}
checkin -d status=in_progress
trap finish EXIT
pg_dump "$DATABASE_URL" | gzip > "/backups/$(date +%F).sql.gz"A finish with no start counts as a run that started its duration ago. For a long job, send a start or pass duration_ms, so the run is placed at the time it began.
A ping URL fits a crontab line, with no key to keep in the environment:
# crontab -e: the ping URL needs no header and no key.
0 3 * * * /usr/local/bin/backup && curl -fsS -m 10 --retry 3 -X POST https://in.littlefriend.io/v1/crons/ping/lfc_YOUR_PING_TOKENDeclare the monitor in the check-in
A JSON body may carry monitor, with the job's schedule, timezone, checkinMargin and maxRuntime in minutes, and name. It is the shape of Sentry's monitor_config, and the snake case names Sentry sends work too. The schedule is a cron expression as a string, or { "type": "crontab", "value" }, or { "type": "interval", "value", "unit" } with a unit of minute, hour, day or week. A new slug creates its monitor, and a changed schedule, margin, max runtime or name updates it, so the code that runs the job also keeps its monitor in step. A new schedule starts counting from the check-in that brought it.
curl -fsS -m 10 --retry 3 https://in.littlefriend.io/v1/crons/weekly-invoices \
-H "Authorization: Bearer $LF_SERVER_KEY" \
-H "Content-Type: application/json" \
-d '
{
"status": "ok",
"duration_ms": 8450,
"monitor": {
"schedule": {
"type": "crontab",
"value": "0 6 * * 1"
},
"timezone": "America/New_York",
"checkinMargin": 15,
"maxRuntime": 30,
"name": "Weekly invoices"
}
}'Answers
A check-in that is recorded answers 202 with the run's check-in id, its status and whether this check-in created the monitor. Pass the id with the finish of a start. Anything else answers { "error": "<reason>" }:
HTTP/1.1 202 Accepted
Content-Type: application/json
{ "checkInId": "run-1761364800-4242", "status": "in_progress", "created": false }401invalid_key: The server key or the ping URL is not one Little Friend knows.404unknown_monitor: No monitor has this slug, and the check-in carries no schedule to create one.400bad_status, bad_checkin_id, bad_duration, bad_message, bad_schedule, bad_timezone, bad_monitor, bad_slug, bad_json: A field is not valid. Nothing is recorded.409monitor_limit: The project already has 50 monitors, so a new slug cannot be created.429rate_limited: More than 60 check-ins a minute for one monitor. Wait for Retry-After.503ingest_busy: The collector is busy for a moment. Try again after Retry-After, as curl --retry does.
Nothing else of the request is stored: no headers, no address, no other field. A start sent twice with the same check-in id is one run, and so is a finish sent twice. Each check-in counts as one event toward the project's daily allowance for events sent with a secret key.
From Node.js
@littlefriend/node wraps a job in one call. monitor sends a start, runs the function, then sends ok or error with the duration and the error's message. It resolves to what the function returns and rethrows what it throws. The third argument declares the monitor, as above, or is just a cron expression.
import { LittleFriend } from '@littlefriend/node';
const lf = new LittleFriend({ key: process.env.LF_SERVER_KEY as string });
await lf.monitor(
'nightly-backup',
async () => {
await backup();
},
{ schedule: '0 3 * * *', timezone: 'Europe/Paris', checkinMargin: 10, maxRuntime: 60 },
);
// Or with just the cron expression, read in UTC:
await lf.monitor('hourly-sync', () => syncInventory(), '0 * * * *');For more control, send each check-in yourself. checkIn returns the check-in id, or null when it could not be sent, and never throws. duration is in milliseconds, message is for errors, and monitor takes the same shape as above.
const id = await lf.checkIn({ slug: 'nightly-backup', status: 'in_progress' });
const started = Date.now();
try {
await backup();
await lf.checkIn({
slug: 'nightly-backup',
status: 'ok',
checkInId: id ?? undefined,
duration: Date.now() - started,
});
} catch (err) {
await lf.checkIn({
slug: 'nightly-backup',
status: 'error',
checkInId: id ?? undefined,
duration: Date.now() - started,
message: 'Backup failed',
});
throw err;
}Check-ins are sent at once, never queued, and retried a few times. A check-in that cannot be sent never fails the job, and a missing one shows up as a missed or timed out run.
Platforms
Any scheduler that can run curl or Node.js works as above. Two hosts need a setting of their own.
Vercel Cron
Vercel Cron calls a path of your app on a schedule. Add the job to vercel.json, then wrap its route handler in monitor with the same schedule. Vercel runs crons in UTC, so leave the time zone out. On the Hobby plan, a job may run at any time within its hour, so set the check-in margin to 60.
{
"crons": [{ "path": "/api/cron/daily-digest", "schedule": "0 8 * * *" }]
}import { LittleFriend } from '@littlefriend/node';
const lf = new LittleFriend({ key: process.env.LF_SERVER_KEY as string });
export async function GET(request: Request): Promise<Response> {
// With CRON_SECRET set, Vercel sends it, so nobody else can start the job.
if (request.headers.get('authorization') !== `Bearer ${process.env.CRON_SECRET}`) {
return new Response('Unauthorized', { status: 401 });
}
await lf.monitor('daily-digest', () => sendDailyDigest(), {
schedule: '0 8 * * *',
// On the Hobby plan, the job may run any time within its hour.
checkinMargin: 60,
maxRuntime: 5,
});
return Response.json({ ok: true });
}Fly scheduled Machines
fly machine run with --schedule hourly, daily, weekly or monthly starts the Machine once in each period, at a time Fly picks. Give its monitor an interval schedule and a generous margin, such as every day with a margin of 1,440 minutes. Keep the server key in a Fly secret, and make the Machine's command a script that checks in when it starts and when it ends.
fly secrets set -a my-jobs LF_SERVER_KEY=lfs_YOUR_SERVER_KEY
littlefriend crons create cleanup --every 1d --margin 1440 --max-runtime 60 --alert
fly machine run registry.fly.io/my-jobs:latest /app/cleanup.sh --schedule daily -a my-jobs#!/bin/sh
# /app/cleanup.sh: the scheduled Machine's command. LF_SERVER_KEY comes from the Fly secret.
set -eu
URL="https://in.littlefriend.io/v1/crons/cleanup"
AUTH="Authorization: Bearer $LF_SERVER_KEY"
ID="fly-$(date +%s)"
curl -fsS -m 10 --retry 3 -o /dev/null "$URL" -H "$AUTH" -d status=in_progress -d check_in_id="$ID" || true
if node dist/cleanup.js; then status=ok; else status=error; fi
curl -fsS -m 10 --retry 3 -o /dev/null "$URL" -H "$AUTH" -d status="$status" -d check_in_id="$ID" || true
[ "$status" = ok ]Missed and timed out runs
Little Friend checks every monitor every 30 seconds. A run that is due and has not checked in by its time plus the margin is recorded as missed. One long gap records at most 60 missed runs, and skips the rest. A started run still going after the max runtime is recorded as timed out, and a finish that arrives later does not change that.
Each run has one of these states:
in_progress: Runningok: OKerror: Failedmissed: Missedtimeout: Timed out
Check-ins are kept 30 days. Deleting a monitor or the project deletes them.
Cron alerts
Two kinds of alert watch a monitor, and a monitor has at most one of each:
- Cron missed (
check_missed) fires after 1 missed run in a row by default, and is over after 1 run in a row that came. - Cron failed (
check_failed) fires after 1 failed or timed out run in a row by default, and is over after 1 run in a row that passed. A missed run neither adds to its streak nor breaks it.
Set either count from 1 to 10. They are decided on every run, not once an hour, and follow the rules of every alert: email and Slack, one alert when it starts and one when it is over, a cooldown, and a longer wait before a job that keeps coming and going is called back to normal. Each links to the Crons page. Deleting a monitor deletes its alerts, and pausing it closes them without a recovery email.
The Crons page
Crons lists each monitor with its state (OK, failed, missed, waiting for its first run, or paused), when its next run is due, and a timeline of its recent runs with their durations. A monitor's history goes back the 30 days its check-ins are kept, and littlefriend crons history narrows it to failed runs or one state.
The same is in the API. Viewers and read keys can read; editors and owners change. History comes in pages of up to 500 runs.
GET /api/projects/:id/crons: Every monitor, with its state, next run and recent runs.POST /api/projects/:id/crons: Create a monitor. The answer holds its ping URL, once.GET /api/projects/:id/crons/:monitor: One monitor.PATCH /api/projects/:id/crons/:monitor: Change, pause or turn on a monitor.DELETE /api/projects/:id/crons/:monitor: Delete a monitor, its runs and its alerts.POST /api/projects/:id/crons/:monitor/ping-url: A new ping URL, shown once. The old one stops working.GET /api/projects/:id/crons/:monitor/history?cursor&limit&status: Runs, newest first, up to 500 a page.