Heartbeat-мониторы

Heartbeat-мониторы позволяют отслеживать работу ваших cron-задач и сервисов. Создайте монитор, получите уникальный URL для пинга, и CronBox уведомит вас, если пинг не получен вовремя.

Как это работает

1. 1

   Создайте монитор

   Выберите тип расписания: фиксированный интервал или cron-выражение. Укажите grace period.

2. 2

   Получите URL для пинга

   Каждый монитор имеет уникальный URL вида https://api.cronbox.ru/ping/abc123

3. 3

   Добавьте пинг в ваш cron

   В конце вашего скрипта отправьте GET-запрос на URL монитора

4. 4

   Получайте уведомления

   CronBox уведомит вас, если пинг не получен в ожидаемое время

Эндпоинты

Типы расписания

Монитор поддерживает два типа расписания: фиксированный интервал и cron-выражение.

Создание монитора (интервал)

curl -X POST https://api.cronbox.ru/v1/workspaces/{workspace_id}/heartbeats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Воркер очереди",
    "schedule_type": "interval",
    "expected_interval": "5m",
    "grace_period": "2m",
    "notify_on_late": true,
    "notify_on_recovery": true
  }'

Создание монитора (cron)

curl -X POST https://api.cronbox.ru/v1/workspaces/{workspace_id}/heartbeats \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ежедневный бэкап",
    "schedule_type": "cron",
    "cron_expression": "0 3 * * *",
    "grace_period": "30m",
    "notify_on_late": true,
    "notify_on_recovery": true
  }'

Формат интервалов

Для режима interval и поля grace_period:

• 5m — 5 минут
• 1h — 1 час
• 24h — 24 часа
• 7d — 7 дней

Примеры cron-выражений

• 0 * * * * — каждый час
• 0 3 * * * — каждый день в 03:00
• 0 9 * * 1-5 — по будням в 09:00
• */5 * * * * — каждые 5 минут
• 0 0 1 * * — 1-го числа каждого месяца

Пинг монитора

Публичный эндпоинт для отправки пинга (не требует авторизации):

Healthchecks.io-совместимые URL

Скрипты, написанные для Healthchecks.io, работают в CronBox без изменений — достаточно поменять хост и токен. Все три формы принимают GET и POST и, как и обычный пинг, всегда отвечают 200 OK — неизвестный или приостановленный монитор неотличим от живого, чтобы токены нельзя было перебрать.

• /ping/{token}/start — задача началась. Состояние монитора не меняется, но следующий обычный пинг сам посчитает длительность выполнения.
• /ping/{token}/fail — задача упала. Монитор сразу переходит в late и отправляет уведомление, не дожидаясь дедлайна (если включено notify_on_late). Повторные сигналы только копят счётчик пропусков и не шлют уведомление второй раз.
• /ping/{token}/{exit_code} — код 0 равен обычному пингу, любой другой работает как /fail, а сам код попадает в текст уведомления.

Тело запроса (лог выполнения, до 4 КБ) сохраняется вместе с успешным пингом: JSON — как есть, любой другой текст — в поле output.

Пример использования в cron

# Crontab: бэкап каждый день в 3:00
0 3 * * * /opt/scripts/backup.sh && curl -fsS https://api.cronbox.ru/ping/abc123

# С сигналом старта: длительность посчитается автоматически
0 3 * * * curl -fsS https://api.cronbox.ru/ping/abc123/start && /opt/scripts/backup.sh && curl -fsS https://api.cronbox.ru/ping/abc123

# С кодом выхода: 0 — успех, всё остальное — падение
0 3 * * * /opt/scripts/backup.sh; curl -fsS https://api.cronbox.ru/ping/abc123/$?

# С логом выполнения в теле запроса
0 3 * * * /opt/scripts/backup.sh 2>&1 | curl -fsS --data-binary @- https://api.cronbox.ru/ping/abc123/0

Статусы монитора