How to Design Health Check Endpoints for Your API

Health check endpoint — точка входа для мониторинга. Если он возвращает 200, ваш сервис считается живым. Если 503 — мёртвым. От того, насколько грамотно спроектирован этот endpoint, зависит, поймаете ли вы реальный outage за 30 секунд или пропустите деградацию, которую заметят только пользователи.

Большинство команд делают минимальный GET /health → 200 OK. Это лучше, чем ничего, но ловит только полную смерть процесса. Настоящий health check проверяет зависимости, различает liveness и readiness, и даёт диагностическую информацию для быстрого troubleshooting.

Два уровня health checks

Liveness: «процесс жив?»

Liveness probe отвечает на один вопрос: приложение запущено и отвечает на запросы? Он не проверяет зависимости — только сам процесс. Если liveness probe не отвечает, Kubernetes перезапускает контейнер, а load balancer перестаёт отправлять трафик.

Liveness должен быть максимально лёгким. Без обращений к базе, кешу, или внешним API. Если ваш liveness probe зависит от базы, то падение базы вызывает каскадный перезапуск всех контейнеров — что только усугубляет ситуацию.

Readiness: «готов принимать трафик?»

Readiness probe отвечает на вопрос: может ли этот экземпляр обработать запрос пользователя? Он проверяет зависимости: базу данных, кеш, очереди, внешние API. Если readiness probe fails, экземпляр выводится из балансировки, но не перезапускается.

{
  "status": "healthy",
  "timestamp": "2026-03-26T10:30:00Z",
  "checks": {
    "database": {"status": "healthy", "latency_ms": 3},
    "redis": {"status": "healthy", "latency_ms": 1},
    "stripe_api": {"status": "healthy", "latency_ms": 45}
  }
}

{
  "status": "degraded",
  "timestamp": "2026-03-26T10:30:00Z",
  "checks": {
    "database": {"status": "healthy", "latency_ms": 3},
    "redis": {"status": "unhealthy", "error": "connection timeout"},
    "stripe_api": {"status": "healthy", "latency_ms": 45}
  }
}

Проектирование dependency checks

Каждая зависимость в readiness probe должна проверяться изолированно с индивидуальным timeout. Один медленный check не должен блокировать весь endpoint.

Database check

# Python / Django
def check_database():
    try:
        start = time.monotonic()
        with connection.cursor() as cursor:
            cursor.execute("SELECT 1")
        latency = (time.monotonic() - start) * 1000
        return {"status": "healthy", "latency_ms": round(latency)}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

Cache check (Redis/Memcached)

def check_redis():
    try:
        start = time.monotonic()
        redis_client.ping()
        latency = (time.monotonic() - start) * 1000
        return {"status": "healthy", "latency_ms": round(latency)}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

External API check

def check_stripe():
    try:
        start = time.monotonic()
        response = requests.get(
            "https://api.stripe.com/healthcheck",
            timeout=5
        )
        latency = (time.monotonic() - start) * 1000
        if response.status_code == 200:
            return {"status": "healthy", "latency_ms": round(latency)}
        return {"status": "degraded", "http_status": response.status_code}
    except requests.Timeout:
        return {"status": "unhealthy", "error": "timeout"}
    except Exception as e:
        return {"status": "unhealthy", "error": str(e)}

Классификация зависимостей: critical vs degraded

Не все зависимости одинаково важны. База данных — critical: без неё ничего не работает. Email сервис — degraded: приложение работает, но письма не уходят. Правильная классификация предотвращает ложное срабатывание health check из-за некритичных сбоев.

def get_overall_status(checks):
    if any(c["status"] == "unhealthy" for name, c in checks.items()
           if name in CRITICAL_DEPS):
        return "unhealthy", 503
    if any(c["status"] != "healthy" for c in checks.values()):
        return "degraded", 200
    return "healthy", 200

Формат ответа

Стандартизированный формат ответа упрощает интеграцию с мониторинг-системами и позволяет использовать JSON path assertions для проверки конкретных полей.

{
  "status": "healthy",
  "version": "2.4.1",
  "uptime_seconds": 86420,
  "timestamp": "2026-03-26T10:30:00Z",
  "checks": {
    "database": {
      "status": "healthy",
      "latency_ms": 3,
      "type": "postgresql"
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 1,
      "type": "redis"
    },
    "queue": {
      "status": "healthy",
      "latency_ms": 2,
      "pending_jobs": 142,
      "type": "celery"
    }
  }
}

В AtomPing вы можете настроить HTTP check с JSON path assertion $.status = healthy. Это проверит не только что endpoint отвечает 200, но и что все зависимости в порядке. Если база упадёт, status сменится на unhealthy, assertion провалится, и мониторинг создаст инцидент.

Kubernetes probes: конфигурация

В Kubernetes liveness и readiness probes настраиваются в манифесте пода. Правильная конфигурация — баланс между скоростью обнаружения и устойчивостью к кратковременным сбоям.

spec:
  containers:
    - name: api
      livenessProbe:
        httpGet:
          path: /health/live
          port: 8000
        initialDelaySeconds: 15
        periodSeconds: 10
        timeoutSeconds: 3
        failureThreshold: 3
      readinessProbe:
        httpGet:
          path: /health/ready
          port: 8000
        initialDelaySeconds: 5
        periodSeconds: 10
        timeoutSeconds: 5
        failureThreshold: 2
      startupProbe:
        httpGet:
          path: /health/live
          port: 8000
        initialDelaySeconds: 0
        periodSeconds: 5
        failureThreshold: 30

startupProbe — третий тип, который даёт приложению время на инициализацию (до 150 секунд в примере выше). Пока startup probe не пройдёт, liveness и readiness не запускаются. Полезно для приложений с тяжёлым стартом (миграции, прогрев кеша, загрузка ML-моделей).

Типичные ошибки

1. Liveness probe с dependency checks

Самая частая ошибка: проверка базы данных в liveness probe. База падает → liveness fails → Kubernetes перезапускает все поды → поды стартуют одновременно → thundering herd на базу → база не восстанавливается. Liveness = только процесс. Dependencies = только readiness.

2. Отсутствие timeout на individual checks

Если один dependency check зависает на 30 секунд (например, DNS resolution timeout к внешнему API), весь health endpoint зависает. Kubernetes интерпретирует это как failure. Решение: выполняйте checks параллельно с индивидуальными timeout (2-5 секунд каждый).

3. Тяжёлые health checks

Health endpoint вызывается каждые 10-30 секунд десятками потребителей (Kubernetes, load balancer, внешний мониторинг). Если check выполняет сложный SQL-запрос или вызывает 5 внешних API, он создаёт ощутимую нагрузку. Правило: health check endpoint должен отвечать за 50-200ms, без исключений.

4. Выдача секретов в health response

Никогда не включайте connection strings, API keys, внутренние IP-адреса, или имена таблиц в ответ health check. Даже если endpoint предназначен «только для внутреннего использования» — утечка одного URL в логи раскрывает вашу инфраструктуру.

5. Единый /health без разделения на liveness/readiness

Один endpoint GET /health вынуждает выбирать: проверять зависимости (и рисковать каскадными перезапусками) или не проверять (и пропускать деградации). Разделение на /health/live и /health/ready решает эту дилемму.

Продвинутые паттерны

Cached readiness

Вместо проверки зависимостей при каждом запросе — запускайте background task, который проверяет их каждые 10-15 секунд и кеширует результат в памяти. Health endpoint возвращает кешированный результат мгновенно. Это снижает нагрузку и предотвращает timeout при высокой частоте запросов.

Graceful degradation signaling

Вместо бинарного healthy/unhealthy используйте три состояния: healthy (всё работает), degraded (некритичные зависимости недоступны, но сервис работает), unhealthy (критичная зависимость недоступна). Мониторинг может по-разному реагировать на каждое состояние: degraded = warning, unhealthy = critical alert.

Deep health vs shallow health

Два endpoint: /health (shallow — быстрая проверка процесса для load balancer, 1-5ms) и /health/deep (полная проверка всех зависимостей для мониторинга, 50-200ms). Load balancer использует shallow, внешний мониторинг — deep. Это разделяет потребности разных потребителей.

Интеграция с внешним мониторингом

Health check endpoint — половина решения. Вторая половина — внешний мониторинг, который регулярно опрашивает этот endpoint из разных регионов и алертит при проблемах.

Внешний мониторинг проверяет то, что Kubernetes probes не могут: доступность через internet (DNS, routing, TLS), производительность с точки зрения пользователя, и работоспособность всей цепочки (CDN → load balancer → app → database).

Checklist: проектирование health check endpoint

Связанные материалы