Heartbeat-мониторинг cron-job'ов: dead-man-switch на FastAPI

Привет, Хабр!

Обычный uptime-мониторинг проверяет, отвечает ли сервис на запросы. Cron-job ничего не отвечает — он запускается раз в N часов, делает работу и молча завершается. Если cron перестал запускаться (uptime daemon упал, машина в read-only mode после fsck, disk full) — обычный мониторинг этого не видит.

Решение известно с 70-х — паттерн dead-man-switch (он же heartbeat). Я недавно делал heartbeat-эндпоинты для Valpero. Здесь разберу серверную часть на FastAPI + клиентский bash-pattern, и edge-кейсы которые их ломают.

В конце готовый код, который можно адаптировать под свой стек.

Концепция

Обычный uptime-чек: «спроси у сервиса, всё ли в порядке».

Dead-man-switch: «жди что сервис сам скажет всё в порядке, и если перестал говорить — алёрт».

Применимо к:

cron-job’ам (0 4 * * * backup.sh)
background workers (Celery, Sidekiq, RQ)
scheduled lambda
любой задаче, которая должна выполниться по расписанию, но не имеет HTTP-endpoint’а

Job делает curl на уникальный URL после успешного завершения:

0 4 * * * /opt/scripts/backup.sh && \ curl -fsS https://example.com/heartbeat/abc123 > /dev/null

Сервер запоминает время последнего ping’а. Если ping не приходит в ожидаемое окно — открывается incident. Окно = interval + grace_period. Для daily-job окно ~25 часов. Если в 5:00 следующего дня после 4:00 ping не пришёл — alert.

Серверная часть на FastAPI

Базовая модель:

from sqlalchemy import Column, Integer, String, Boolean, DateTime from app.database import Base

class HeartbeatMonitor(Base): tablename = “heartbeat_monitors” id = Column(Integer, primary_key=True) user_id = Column(Integer, nullable=False, index=True) name = Column(String(120), nullable=False) token = Column(String(40), unique=True, nullable=False, index=True) interval_sec = Column(Integer, nullable=False) # 24*3600 для daily grace_sec = Column(Integer, nullable=False) # 3600 = 1h допуск last_ping_at = Column(DateTime, nullable=True) state = Column(String(20), default=“pending”) # pending/up/down

interval_sec + grace_sec — это окно, в которое должен прийти ping. Если не пришёл — state = down.

Endpoint для приёма ping’а:

from fastapi import APIRouter, Request, Depends from fastapi.responses import Response from datetime import datetime, UTC from sqlalchemy import select from app.database import get_db

router = APIRouter()

@router.post(“/heartbeat/{token}”) @router.get(“/heartbeat/{token}”) # дублируем для curl без --data async def heartbeat(token: str, request: Request, db = Depends(get_db)): monitor = (await db.execute( select(HeartbeatMonitor).where(HeartbeatMonitor.token == token) )).scalar_one_or_none() if not monitor: return Response(status_code=404)

now = datetime.now(UTC)
exit_code = int(request.query_params.get("exit", 0))

# Запись пинга
ping = HeartbeatPing(
    monitor_id=monitor.id,
    received_at=now,
    exit_code=exit_code,
)
db.add(ping)

monitor.last_ping_at = now
if exit_code != 0:
    # Job завершился с ошибкой — алёрт сразу
    await open_incident(db, monitor, f"Heartbeat exit code {exit_code}")
    monitor.state = "down"
else:
    # Job ОК — закрываем incident если был открыт
    if monitor.state == "down":
        await close_incident(db, monitor)
    monitor.state = "up"

await db.commit()
return Response(status_code=200)

Background-таска проверяет overdue heartbeats каждую минуту:

from celery import shared_task from datetime import timedelta

@shared_task async def check_overdue_heartbeats(): now = datetime.now(UTC) async with async_session_factory() as db: result = await db.execute(select(HeartbeatMonitor).where( HeartbeatMonitor.last_ping_at.isnot(None), HeartbeatMonitor.state != “down”, )) for monitor in result.scalars(): deadline = monitor.last_ping_at + timedelta( seconds=monitor.interval_sec + monitor.grace_sec ) if now > deadline: await open_incident( db, monitor, f"Heartbeat overdue by {(now-deadline).total_seconds():.0f}s" ) monitor.state = “down” await db.commit()

В Celery beat: check_overdue_heartbeats.s().apply_async(countdown=60) каждую минуту.

Клиентский pattern

Простейший case — curl после успеха:

0 4 * * * /opt/scripts/backup.sh && \ curl -fsS --retry 3 --retry-delay 10 \ "https://example.com/heartbeat/abc123" > /dev/null

--retry 3 --retry-delay 10 — на случай если ваш monitoring-сервер недоступен в момент пинга. Лучше повторить, чем потерять heartbeat.

С exit-code reporting:

0 4 * * * /opt/scripts/backup.sh; \ curl -fsS "https://example.com/heartbeat/abc123?exit=$?" > /dev/null

Точка с запятой вместо && — чтобы curl выполнился даже если job упал. $? подставит exit code предыдущей команды.

Start + end pings — если важно поймать «job запустился но завис»:

0 4 * * * curl -fsS "https://example.com/heartbeat/abc123/start" > /dev/null && \ /opt/scripts/backup.sh && \ curl -fsS "https://example.com/heartbeat/abc123/end" > /dev/null

Сервер ждёт пару start+end в течение max_duration. Если только start без end — алёрт.

Heartbeat-as-pipe через wrapper-утилиту:

0 4 * * * /usr/local/bin/heartbeat backup-prod -- /opt/scripts/backup.sh

Утилита сама делает start, запускает команду, ловит exit-code и логи stdout/stderr, посылает end с метаданными. Это самый чистый вариант для production.

Edge-кейсы которые ломают heartbeat

Cron jitter. Job на 0 4 * * * запускается в 04:00:00 — но реально может пускаться в 04:00:08-04:00:15 если у вас одновременно много scheduled tasks. Если grace_period = 30 секунд — false-positive. Минимум для daily-job: 5 минут. Для hourly: 2 минуты. Для каждые-5-минут: 30 секунд.

Время работы job скачет. Backup растущей базы — сегодня 10 минут, через месяц 18 минут. Если max_duration = 15 минут — false-positive после роста базы. Ставить max_duration минимум 3× от среднего и пересматривать раз в квартал.

Network outage между job и monitor. Job отработал, но curl на heartbeat не дошёл из-за DNS-проблем или network issue. Решение: --retry 5 --retry-delay 10 --retry-connrefused чтобы curl сам повторил. Плюс — игнорировать первый missed heartbeat, алёртить только на второй подряд.

Timezone drift. Cron работает в локальной TZ системы. Если ваш VPS в US-East, job на 0 4 * * * запускается в 4 утра US-East. Если monitor ждёт ping в 04:00 UTC — 5-часовой gap → false-positive. Решение: CRON_TZ=UTC в crontab или в самом scheduler если возможно.

Disk full на машине с job’ом. Job не может писать stdout/stderr — может зависнуть или упасть без exit-code. Идея: heartbeat-утилита должна иметь fallback на in-memory log если disk full.

Что в итоге

Heartbeat-мониторинг — классический паттерн который должен быть у каждого, кто запускает cron в продакшне. Серверная часть пишется за полдня на FastAPI + Postgres. Клиентский pattern — одна строчка curl в конце job’а.

Если запиливаешь свой мониторинг, добавь heartbeat-endpoint раньше, чем красивый дашборд. Heartbeat ловит классы проблем, которые обычный uptime не видит — а это значимая часть всех «у нас тут что-то не так».

Ссылки

Сайт: valpero.com — у меня в Valpero heartbeat доступен на free плане, 1 монитор без карты

推荐订阅源

Все публикации подряд на Хабре