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 уведомит вас, если пинг не получен в ожидаемое время

Эндпоинты

GET
/heartbeats

Список мониторов

POST
/heartbeats

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

GET
/heartbeats/{id}

Получение монитора

PATCH
/heartbeats/{id}

Обновление монитора

DELETE
/heartbeats/{id}

Удаление монитора

POST
/heartbeats/{id}/pause

Приостановка монитора

POST
/heartbeats/{id}/resume

Возобновление монитора

GET
/heartbeats/{id}/pings

История пингов

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

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

interval — Интервал

Следующий пинг ожидается через фиксированный промежуток после предыдущего. Подходит для задач с плавающим временем запуска.

Поля: expected_interval (обязательно)

cron — Cron-расписание

Следующий пинг ожидается в соответствии с cron-выражением. Точно соответствует расписанию вашей задачи — нет дрейфа времени.

Поля: cron_expression (обязательно)

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

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
  }'

Когда использовать cron-режим? Если ваша задача запускается по фиксированному расписанию (например, 0 3 * * *), cron-режим точнее определяет дедлайн для каждого пинга — без накопленного дрейфа.

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

Для режима 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-го числа каждого месяца

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

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

GET
/ping/{token}

Отправка пинга (публичный)

POST
/ping/{token}

Отправка пинга с данными

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

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

# Или с проверкой exit code
0 3 * * * /opt/scripts/backup.sh; curl https://api.cronbox.ru/ping/abc123?exit_code=$?

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

healthy

Пинг получен вовремя, всё работает нормально

waiting

Ожидание первого пинга или находится в grace period

late

Пинг не получен в ожидаемое время - возможна проблема

Совет: Устанавливайте grace period с запасом. Если скрипт обычно выполняется 10 минут, grace period должен быть 15–20 минут. В cron-режиме дедлайн = следующий тик расписания + grace period.

← Цепочки задач
SSL-мониторинг →