Подробный гайд: Health Check для Grafana в Docker Health Check (проверка работоспособности) в Docker позволяет контейнеру самостоятельно сообщать оркестратору или хосту о своём состоянии. Для Grafana это критически важно, так как приложение проходит несколько этапов инициализации: загрузка конфигурации, миграция БД, инициализация плагинов и прогрев кэша. Без health check контейнер может считаться запущенным (running), хотя веб-интерфейс и API ещё не отвечают.

---

Зачем нужен health check для Grafana?

1. Корректная маршрутизация трафика (Traefik, Nginx Proxy Manager, Docker Swarm, Kubernetes).
2. Автоматический рестарт при зависании или аварийном падении процесса.
3. Безопасный деплой (rolling updates не направляют запросы на ещё не готовый инстанс).
4. Мониторинг и алертинг через стандартные Docker-события или exporters.

---

Как работает Docker Health Check?

Docker периодически выполняет указанную команду внутри контейнера.

В зависимости от кода возврата выставляется статус:

• starting — контейнер запущен, но ещё не прошёл проверки
• healthy — команда вернула 0
• unhealthy — команда возвращала ошибку retries раз подряд

Стандартные параметры:

Параметр	Описание	Рекомендация для Grafana
interval	Частота проверки	30s
timeout	Макс время выполнения	10s
retries	Кол-во ошибок до смены статуса	3
start_period	Время на инициализацию до начала учёта ошибок	40s–60s

---

Готовый пример docker-compose.yml

services:
  grafana:
    image: grafana/grafana:11.1.0
    container_name: grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_USER=admin
      - GF_SECURITY_ADMIN_PASSWORD=changeme
      - GF_SERVER_ROOT_URL=http://localhost:3000
    volumes:
      - grafana-/var/lib/grafana
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 50s

volumes:
  grafana-

Примечание:

• Начиная с Docker Compose v2 поле version больше не требуется и считается устаревшим.

---

Альтернативные варианты healthcheck

1. Через wget (если curl отсутствует)

healthcheck:
  test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:3000/api/health || exit 1"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 50s

2. Через sh с проверкой HTTP-кода

healthcheck:
  test: ["CMD-SHELL", "status=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:3000/api/health); [ \"$status\" = \"200\" ] || exit 1"]

3. В Dockerfile (для кастомных образов)

FROM grafana/grafana:11.1.0
HEALTHCHECK --interval=30s --timeout=10s --retries=3 --start-period=50s \
  CMD curl -f http://localhost:3000/api/health || exit 1

---

Особенности Grafana при настройке health check

Аспект	Что важно знать
Эндпоинт	/api/health возвращает 200 OK и JSON {"commit":"...","database":"ok","version":"x.x.x"}. Не требует аутентификации.
Инициализация БД	При первом запуске или после обновления версии Grafana выполняет миграции. start_period должен покрывать это время.
Плагины	Установка/обновление плагинов через GF_INSTALL_PLUGINS или volume может сильно увеличить время старта. Увеличьте start_period до 90s, если используете много плагинов.
Внешняя БД	Health check не проверяет подключение к PostgreSQL/MySQL/SQLite. Он лишь подтверждает, что процесс Grafana жив и отвечает на HTTP. Для проверки БД используйте отдельные скрипты или алерты внутри Grafana.
Reverse Proxy	Проверка всегда идёт через localhost внутри контейнера. Прокси (Traefik, Nginx) должен использовать именно Docker healthcheck, а не свои собственные проверки портов.

---

Как мониторить статус health check

1. Быстрая проверка в CLI

docker ps --filter "name=grafana" --format "table {{.Names}}\t{{.Status}}"

2. Детальный вывод

docker inspect --format='{{json .State.Health}}' grafana | jq

Пример вывода:

{
  "Status": "healthy",
  "FailingStreak": 0,
  "Log": [
    {
      "Start": "2024-05-10T12:00:00Z",
      "End": "2024-05-10T12:00:01Z",
      "ExitCode": 0,
      "Output": ""
    }
  ]
}

3. Интеграция с Prometheus

Используйте docker-exporter или cadvisor для сбора метрик:

• container_healthcheck_failure{container="grafana"}
• container_healthcheck_status{container="grafana"}

---

Troubleshooting

Симптом	Причина	Решение
Контейнер всегда starting	start_period слишком мал или процесс завис	Увеличьте start_period до 60s–90s, проверьте логи: docker logs grafana
Статус unhealthy	/api/health возвращает не 200	Проверьте доступность порта внутри контейнера: docker exec grafana curl -v http://localhost:3000/api/health
command not found: curl	В образе нет curl	Замените на wget или добавьте установку в Dockerfile: RUN apt-get update && apt-get install -y curl
Healthcheck проходит, но веб-интерфейс не отвечает	Grafana слушает только 127.0.0.1, а прокси стучится на 0.0.0.0	Убедитесь, что GF_SERVER_HTTP_ADDR=0.0.0.0 (по умолчанию в образе уже так)
Частые false-positive unhealthy	timeout слишком мал для нагруженной БД	Увеличьте timeout: 15s и retries: 4

---

Best Practices

1. Всегда задавайте start_period ≥ 40s для Grafana.
2. Используйте фиксированную версию образа (grafana/grafana:11.1.0 вместо latest в продакшене).
3. Не логируйте чувствительные данные через healthcheck-команды (используйте curl -s, а не -v в production).
4. Для Kubernetes используйте readinessProbe и livenessProbe с тем же эндпоинтом /api/health.
5. Регулярно проверяйте логи при смене статуса healthy ↔ unhealthy – это ранний индикатор проблем с дисками, памятью или БД.

---

Ссылки

• Официальная документация Docker Healthcheck: docs.docker.com/reference/dockerfile/#healthcheck
• Grafana API Health: grafana.com/docs/
• Рекомендуемые параметры для production: grafana.com/docs/grafana/latest/setup-grafana/installation/docker/