Назад в блог

Мониторинг cron-задач с Healthchecks.io: push-уведомления на телефон, когда задача падает или не запускается

Мониторинг cron-задач с Healthchecks.io: push-уведомления на телефон, когда задача падает или не запускается

Cron-задача может сломаться двумя способами. Она может запуститься и упасть: pg_dump не может подключиться к базе, на диске закончилось место. Или она вообще перестаёт запускаться: строку в crontab удалили, сервер пересобрали без неё, демон cron мёртв. Первый вид оставляет ошибку где-то в логах. Второй не оставляет ничего, и вы узнаёте об этом в тот день, когда понадобился вчерашний бэкап.

Алертинг, который ждёт, что задача сама скажет «я упала», никогда не услышит от задачи, которая не запустилась. Чтобы поймать такой сбой, нужна обратная схема: задача сообщает о себе каждый раз, когда завершается, а что-то другое поднимает тревогу, если сообщение не пришло.

Этот гайд строит такую схему на Healthchecks.io, открытом мониторе cron-задач, а его алерты отправляет на ваш телефон через Pocket Alert. Падения приходят громко, восстановления тихо. Всё ниже проверено на self-hosted Docker-образе Healthchecks v5.0.3, на облачном сервисе работает так же.

Что понадобится

  • Аккаунт Healthchecks на healthchecks.io (бесплатный тариф Hobbyist мониторит 20 задач) или собственный инстанс из Docker-образа healthchecks/healthchecks.
  • Приложение Pocket Alert на iPhone или Android и API-ключ из API Keys. Для начала хватит бесплатного тарифа.
  • curl на машине, где работают cron-задачи.

Dead man's switch

В Healthchecks это называется мониторингом heartbeat, или «переключателем мёртвой руки» (dead man's switch). Каждой задаче создаётся check с уникальным ping-URL, который задача вызывает по завершении. Если следующий запрос не пришёл вовремя, check переходит в статус down и отправляются алерты.

За понятие «вовремя» отвечают два параметра:

  • Period — как часто вы ждёте ping: каждый час, каждый день.
  • Grace time — сколько Healthchecks ждёт после ожидаемого времени, прежде чем объявить падение. Задайте его больше обычного времени работы задачи с запасом.

Для cron-задачи выберите тип расписания Cron и вставьте выражение из crontab, а также часовой пояс сервера. Тогда Healthchecks будет ждать ping в нужное время суток, а не просто через нужные интервалы. Редактор cron-выражений объясняет, что означает каждое выражение.

В нашем тесте check с расписанием */2 * * * * и grace time в одну минуту получил ping в 16:09:13. В 16:10 ping не пришёл, и в 16:11:00, ровно через один grace period, check перешёл в down.

У ping-URL есть несколько вариантов:

ЗапросЗначение
https://hc-ping.com/<uuid>Успех. Задача завершилась.
https://hc-ping.com/<uuid>/startЗадача начала работу. Healthchecks теперь ждёт успешного завершения в пределах grace time и записывает длительность запуска.
https://hc-ping.com/<uuid>/failЗадача упала. Check сразу переходит в down.
https://hc-ping.com/<uuid>/<0-255>Код выхода. 0 считается успехом, любое другое значение — падением.

На self-hosted инстансе база — ваш домен плюс /ping/, например https://hc.example.com/ping/<uuid>.

Подключаем cron-задачу

Создайте check, скопируйте его ping-URL и измените строку crontab. Мы запускали это под демоном cron на Debian 13:

PING=https://hc-ping.com/your-check-uuid
15 3 * * * curl -fsS -m 10 --retry 5 -o /dev/null $PING/start; /usr/local/bin/backup.sh; curl -fsS -m 10 --retry 5 -o /dev/null $PING/$?

PING= — это переменная crontab, которую shell подставляет в команду. Строка делает три вещи:

  • Отправляет /start, поэтому зависшая задача перейдёт в down, когда истечёт grace time. В нашем тесте /start без последующего сообщения переводил check в down ровно через один grace period.
  • Запускает задачу.
  • Отправляет $?, код выхода задачи. Успешный запуск шлёт /0, упавший — /2 или любое значение, которое вернул скрипт, и check сразу переходит в down.

Флаги curl не дают самому ping создавать проблемы:

  • -m 10 ограничивает каждый запрос 10 секундами. Зависший /start не должен задерживать задачу.
  • --retry 5 повторяет запрос при таймауте и ответах 408, 429, 500, 502, 503 и 504, с растущими паузами. Одна потерянная пачка пакетов не должна вас будить.
  • -fsS заставляет curl завершаться с ошибкой при HTTP-ошибках и молчать, пока всё в порядке, чтобы cron не присылал вам индикатор прогресса curl.
  • -o /dev/null отбрасывает тело ответа, которое состоит из OK.

Если задача представляет собой конвейер вроде pg_dump | gzip > dump.gz, её код выхода — это код gzip, а не pg_dump. Вынесите команду в скрипт с set -o pipefail в bash, чтобы упавший дамп не отчитывался как успешный.

Или пусть это сделает runitor

runitor — небольшой бинарник на Go, который оборачивает команду и сам отправляет ping: /start до запуска, код выхода после, а последние 10 000 байт вывода команды прикрепляются к ping.

curl -fsSL -o /usr/local/bin/runitor https://github.com/bdd/runitor/releases/download/v1.4.1-build.6/runitor-v1.4.1-build.6-linux-amd64
chmod +x /usr/local/bin/runitor

Строка crontab становится короче:

15 3 * * * CHECK_UUID=your-check-uuid /usr/local/bin/runitor -- /usr/local/bin/backup.sh

Для self-hosted инстанса добавьте HC_API_URL=https://hc.example.com/ping. Мы запускали runitor v1.4.1 так под cron: упавший бэкап перевёл check в down с кодом выхода 2, а текст ошибки попал в алерт.

Отправляем алерты в Pocket Alert

Healthchecks подключается к Pocket Alert через универсальную интеграцию Webhook. Откройте Integrations, найдите Webhook и нажмите Add Integration. Форма состоит из двух блоков, «Execute when a check goes down» и «Execute when a check goes up», у каждого свой URL, метод, тело и заголовки. Такое разделение позволяет сделать «падение» громким, а «восстановление» тихим.

В обоих блоках можно использовать плейсхолдеры: $NAME, $NAME_JSON, $STATUS, $NOW, $CODE, $SLUG, $TAGS, $EXITSTATUS, $BODY, $BODY_JSON, $JSON и несколько других. В JSON-телах обратите внимание на разницу: $NAME вставляется как есть, поэтому check с именем Nightly "db" backup сломает JSON, а $NAME_JSON — это готовая JSON-строка вместе с кавычками. То же относится к $BODY и $BODY_JSON.

Вариант 1: напрямую в API

В блоке down выберите POST и URL https://api.pocketalert.app/v1/messages. Заголовки запроса, по одному на строку:

Content-Type: application/json
Token: YOUR_API_KEY

Тело запроса:

{
  "title": $NAME_JSON,
  "message": "DOWN since $NOW. Exit status of the last ping: $EXITSTATUS",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/$CODE/details/"}]
}

В блоке up тот же метод, URL и заголовки, а тело тише:

{
  "title": $NAME_JSON,
  "message": "Back up at $NOW",
  "level": "low"
}

Нажмите Save Integration. Новая интеграция подключается ко всем существующим check в проекте. Вот что отправил Healthchecks, когда наш тестовый check упал:

{
  "title": "Nightly \"db\" backup",
  "message": "DOWN since 2026-10-31T16:15:01+00:00. Exit status of the last ping: 2",
  "level": "high",
  "actions": [{"type": "view", "label": "Open check", "value": "https://healthchecks.io/checks/a4b72803-3a50-4b81-b33f-88dd2200ffc2/details/"}]
}

Несколько замечаний к этому телу:

  • high — для срочного. Такое уведомление пробивает Фокусирование и плановую сводку. На платном тарифе замените на critical, и упавшая задача бэкапа разбудит вас даже при выключенном звуке и режиме «Не беспокоить». На бесплатном тарифе critical принимается и доставляется как high.
  • low для восстановлений. «Back up» попадает в ленту без звука. Вам это важно знать, но не в 3 часа ночи.
  • $EXITSTATUS отличает падение от пропуска. Это код выхода последнего ping перед алертом. 2 означает, что задача запустилась и вернула 2. Down с 0 означает, что последний запуск прошёл успешно, а следующий так и не состоялся. -1 означает, что последний ping не содержал кода выхода: обычный URL успеха, /fail или /start.
  • Кнопка открывает check в Healthchecks. Для self-hosted инстанса укажите в URL свой домен. Кнопки действий — платная функция; на бесплатном тарифе они удаляются, а само сообщение доставляется как обычно.

Вариант 2: вебхук Pocket Alert с шаблоном

Второй способ отправляет небольшой JSON-документ на вебхук Pocket Alert, который уже формирует push-уведомление. Его преимущество: в уведомление можно включить вывод задачи.

Откройте Webhooks в консоли Pocket Alert, создайте вебхук с именем Healthchecks и задайте шаблон сообщения:

%name% is %status% since %time%
%log%

Оставьте Default priority не выбранным, потому что приоритет передаётся в самом payload. Скопируйте URL вебхука, который выглядит как https://p4a.me/wh/abc123xyz. Сам URL является секретом, обращайтесь с ним как с паролем.

В Healthchecks создайте интеграцию Webhook с этим URL как POST в обоих блоках, заголовком Content-Type: application/json и следующими телами. Для падения:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "high"}

Для восстановления:

{"name": $NAME_JSON, "status": "$STATUS", "time": "$NOW", "code": "$CODE", "log": $BODY_JSON, "level": "low"}

$BODY_JSON — это тело последнего ping, именно туда runitor кладёт вывод задачи. Когда обёрнутый в runitor бэкап упал в нашем тесте, push выглядел так:

Webhook Healthchecks
DB backup (runitor) is down since 2026-10-31T16:15:02+00:00
dumping appdb
pg_dump: error: connection to server on socket failed: No such file or directory

[runitor] exit status 2

Pocket Alert читает верхнеуровневое поле level входящего payload, поэтому high и low работают так же, как в варианте 1. Без runitor $BODY_JSON — пустая строка, и вторая строка остаётся пустой. API так не умеет: $BODY_JSON — это готовая JSON-строка, поэтому он может быть только целым message, а если ping не содержал тела, сообщение пустое и API его отклоняет.

Есть и другие отличия: заголовок push всегда Webhook <name>, поэтому имя check попадает в текст сообщения, а кнопки вебхука задаются через поле actions в API вебхуков, а не через форму в консоли.

Проверка

На странице Integrations в Healthchecks у каждой интеграции есть кнопка Test!. Она отправляет уведомление о падении для check с именем TEST, которое приходит как push с приоритетом high. Затем запустите задачу, которая завершается с кодом 1, и дождитесь настоящего алерта.

Без Healthchecks: обёртка, которая присылает push при падении

Если не хочется подключать ещё один сервис, короткая обёртка покроет самый частый случай: задача завершилась с ошибкой. Сохраните её как /usr/local/bin/cron-alert:

#!/bin/sh
# Usage: cron-alert <job name> <command> [args...]
name="$1"
shift

log=$(mktemp)
"$@" >"$log" 2>&1
status=$?

if [ "$status" -ne 0 ]; then
  curl -fsS -m 10 --retry 3 --retry-max-time 30 -o /dev/null \
    -H "Token: $POCKETALERT_API_KEY" \
    --form-string "title=Cron failed: $name on $(hostname)" \
    --form-string "message=Exit status $status. $(tail -c 2000 "$log")" \
    --form-string "level=high" \
    "${POCKETALERT_API_URL:-https://api.pocketalert.app/v1/messages}"
fi

cat "$log"
rm -f "$log"
exit "$status"

А в crontab:

POCKETALERT_API_KEY=your-api-key
15 3 * * * /usr/local/bin/cron-alert "nightly backup" /usr/local/bin/backup.sh

Несколько осознанных решений:

  • --form-string вместо JSON. API принимает данные multipart/form-data, а --form-string передаёт вывод как есть, с кавычками и переводами строк, без jq и экранирования. Обычный -F воспринял бы значение, начинающееся с @ или <, как путь к файлу.
  • tail -c 2000 сохраняет конец вывода, где обычно и находится ошибка.
  • --retry-max-time 30 важен. При превышении дневного лимита сообщений API отвечает 429 с Retry-After, равным числу секунд до полуночи UTC, и --retry curl это учитывает. В нашем тесте без этого флага curl ждал Retry-After: 30000, пока мы его не остановили. С флагом curl сдаётся после одной попытки.
  • Обёртка сохраняет код выхода и выводит лог, поэтому журналы cron и MAILTO работают как раньше.

Скрипт проходит shellcheck, а при запуске под cron на Debian 13 упавший бэкап пришёл как «Cron failed: nightly backup on» с именем хоста и текстом ошибки pg_dump в сообщении.

Важно понимать, что обёртка не умеет. Она работает только тогда, когда cron её запускает. Если строку crontab удалили, демон остановлен или машина выключена, ничего не отправляется: это и есть тихий сбой из начала статьи. Задача, которая зависла навсегда, тоже останется незамеченной. Для таких случаев нужно что-то вне машины, что ждёт heartbeat, именно для этого и существует Healthchecks. CLI Pocket Alert может заменить вызов curl, если вам так удобнее.

Честные ограничения

  • Healthchecks должен быть доступен, чтобы заметить сбой. В облачном сервисе это его задача. Если вы разворачиваете его на той же машине, что и cron-задачи, то упавшая машина утащит за собой и монитор. Запускайте его где-то в другом месте.
  • Шаблон тела ограничен 1 000 символами в Healthchecks. Для примеров выше этого достаточно, а для длинного рукописного сообщения — нет.
  • Длинный вывод обрезается в push. Push содержит примерно первые 3 КБ сообщения; полный текст находится в истории сообщений в приложении.
  • Каждый алерт — это одно сообщение. Нестабильная задача, которая каждые несколько минут падает и восстанавливается, присылает push каждый раз, а на бесплатном тарифе с лимитом 50 сообщений в день это быстро накапливается. Почините задачу или увеличьте grace time.

Если ничего не приходит

  • Сначала используйте кнопку Test! Если тест пришёл, а реальные алерты нет, проверьте, что интеграция включена для этого check, на странице самого check.
  • Посмотрите страницу Integrations в Healthchecks. Неработающая интеграция помечается там как Failed; наведите на неё курсор, чтобы увидеть последнюю ошибку, например Received status code 401. Код 401 означает, что заголовок Token неверный. Код 400 обычно значит, что тело не является корректным JSON: проверьте, что вы использовали $NAME_JSON без кавычек вокруг, а не "$NAME".
  • Новый check не отправляет алерты до первого ping. До этого момента он в статусе «new», а не «down».
  • Проверьте часовой пояс cron-check. Если check всегда срабатывает на час раньше или позже, часовой пояс сервера не совпадает с тем, что указан в check.
  • Посмотрите в ленте. Push с low не издают звука, поэтому восстановление может показаться так, будто оно вообще не пришло.

FAQ

Использовать маршрут через API или через вебхук?

Маршрут через API помещает имя check в заголовок push и не требует ничего создавать в Pocket Alert. Маршрут через вебхук может включать вывод задачи, поэтому если вы используете runitor, выбирайте вебхук.

Можно получать только алерты о падении?

Да. Используйте тихое тело с low для «up», как выше, или оставьте URL для «up» пустым, и Healthchecks не будет ничего отправлять при восстановлении.

А что с systemd-таймерами?

Идея та же. В Healthchecks есть тип расписания **OnCalendar», который принимает те же выражения, что и ваш таймер. Отправляйте /start из ExecStartPre или оборачивайте команду ExecStart в runitor.

Где почитать больше об алертах cron?

На странице алерты cron-задач описано, как отправлять push из самой задачи, алерты бэкапов посвящена инструментам резервного копирования, а гайд по Proxmox — бэкапам на гипервизоре.

Создайте бесплатный аккаунт, добавьте одну интеграцию Webhook в Healthchecks и пусть задача, которая тихо перестала запускаться, будет тем, что вас разбудит.

Поделиться статьёй