ТЕХНИЧЕСКОЕ ЗАДАНИЕ: Настроить health checks для всех компонентов

1. Цель задачи

Обеспечить 100% покрытие health checks для всех ключевых компонентов production LLM-системы: LLM API, векторной базы данных, embedding API и Redis. Health checks — это механизмы, позволяющие автоматически детектировать недоступность, деградацию или неправильное поведение каждого компонента. Выполнив задачу, вы научитесь проектировать и внедрять надёжные health probes, которые станут основой для алертов и автоматических восстановлений.

Ключевой результат набор конфигураций, скриптов и дашбордов, гарантирующий, что любой сбой любого из перечисленных компонентов будет зафиксирован в течение не более 30 секунд.

2. Исходные данные

Перед началом необходимо иметь:

Если нет реального инструмента — симулируем:

1. Разверните минимальный стек через Docker Compose с четырьмя сервисами (LLM API — например, Ollama, vector DB — Qdrant, embedding API — text-embedding-3-small через OpenAI proxy, Redis).
2. Для симуляции отсутствия health endpoint у какого-либо компонента — создайте простой HTTP-сервер на Python с одним эндпоинтом /health, который возвращает 200 OK. Этого будет достаточно для отработки логики.

3. Технологический стек

4. Этапы выполнения

Этап 1: Определение критериев health для каждого компонента (1 час)

Действия

1. Для каждого компонента составьте список минимальных признаков «здоровья». Включите не только статус «жив» (liveness), но и готовность (readiness) — способность обрабатывать запросы.

2. Заполните таблицу:

   Компонент	Liveness критерий	Readiness критерий
   LLM API	HTTP-ответ 200 на /health (если есть) или ответ на простой prompt "ping"	Модель не выгружена, время первого токена < 5 с
   Vector DB	HTTP-ответ 200 на /health (Qdrant) или ping (RedisJSON)	Коллекции доступны, индекс не перестраивается
   Embedding API	HTTP-ответ 200 на /health (если есть) или ответ на запрос эмбеддинга пустой строки	Скорость выдачи < 1 с
   Redis	PONG на PING	Загрузка памяти < 90%, количество подключений < max

3. Определите, какие health checks уже реализованы «из коробки» в используемых версиях, а какие нужно написать самостоятельно.

Ожидаемый результат этапа Документ (Markdown) с таблицей критериев health для всех компонентов.

Этап 2: Реализация / настройка health endpoints (1.5–2 часа)

Действия

1. LLM API

   • Если используется Ollama: curl http://localhost:11434/api/tags — если возвращает 200, жив. Дополнительно можно проверить доступность конкретной модели через ollama show <model>.
   • Если используется OpenAI API: health check сводится к HTTP-статусу эндпоинта https://api.openai.com/v1/models (требуется API-ключ). Для liveness можно использовать заглушку.
   • Напишите Python-скрипт llm_health.py, который делает запрос с самым маленьким промптом ("test") и проверяет, что время отклика < 5 с.

2. Vector DB (Qdrant):

   • Встроенный /health возвращает 200, если сервер жив. Проверяем curl http://localhost:6333/health.
   • Для readiness можно проверить, что все коллекции имеют статус "green" (не восстанавливаются). Используйте API /collections/{collection_name} и смотрите поле status.

3. Embedding API

   • Если используется локальный server (например, sentence-transformers + Flask), создать эндпоинт /health, возвращающий 200.
   • Для OpenAI Embeddings — проверить доступность через curl с минимальным запросом.

4. Redis

   • Использовать встроенный PING через redis-cli ping или библиотеку redis-py. Пример скрипта:

   import redis
   import sys
   r = redis.Redis(host='localhost', port=6379, socket_connect_timeout=5)
   try:
       r.ping()
       print("OK")
   except Exception as e:
       print(f"FAIL: {e}")
       sys.exit(1)
   

5. Оформите каждый health check как отдельный endpoint (если это сервис) или как консольную команду (для Prometheus blackbox exporter).

6. Добавьте health check в docker-compose — для каждого сервиса определите healthcheck секцию (используя curl или наш скрипт).

   Пример для Redis в docker-compose:

   services:
     redis:
       image: redis:7
       healthcheck:
         test: ["CMD", "redis-cli", "ping"]
         interval: 10s
         timeout: 5s
         retries: 3
   

Ожидаемый результат этапа Рабочие health check endpoints (или консольные скрипты) для всех четырёх компонентов. Docker-compose с healthcheck секциями.

Этап 3: Интеграция с Prometheus и сбор метрик (1–1.5 часа)

Действия

1. Установите Prometheus (если ещё нет) – можно через тот же docker-compose.

2. Создайте конфигурацию prometheus.yml, добавив три типа сборщиков:

   • Статичные таргеты – если у вас есть HTTP-эндпоинты /health (например, у Qdrant).
   • Blackbox exporter – для компонентов, у которых нет HTTP (например, Redis). Blackbox exporter будет выполнять по ICMP/TCP/HTTP проверки.
   • Pushgateway – если скрипты health check запускаются по cron и могут отправлять метрики.

   Пример части конфигурации (для Qdrant):

   scrape_configs:
     - job_name: 'qdrant_health'
       static_configs:
         - targets: ['qdrant:6333']
       metrics_path: '/health'
   

3. Настройте алерты в Prometheus (rules). Пример правила для Redis, основанного на метриках blackbox (значение 0 = dead, 1 = alive):

   groups:
     - name: health_alerts
       rules:
         - alert: RedisDown
           expr: probe_success{target="redis://redis:6379"} == 0
           for: 1m
           labels:
             severity: critical
           annotations:
             summary: "Redis instance {{ $labels.target }} is down"
   

4. Убедитесь, что все метрики health появляются в Prometheus – проверьте на http://localhost:9090/targets.

Ожидаемый результат этапа Prometheus с активными таргетами, собирающий метрики health. Настроено хотя бы одно алерт правило.

Этап 4: Графическая визуализация (Grafana) и дашборд (1 час)

Действия

1. Установите Grafana (если нет) и подключите к Prometheus.
2. Создайте дашборд «Health Checks Overview» с панелями:
   • Status panel – probe_success для каждого компонента (1/0). Используйте таблицу или single stat.
   • Response time panel – probe_duration_seconds (среднее за 5 минут) для тех компонентов, где есть HTTP health.
   • Uptime panel – time() - process_start_time_seconds (для тех, кто экспортирует метрики Go/Rust).
3. Добавьте переменные для переключения окружений (если разные).
4. Экспортируйте дашборд в JSON для повторного использования.

Ожидаемый результат этапа Рабочий дашборд Grafana, отображающий состояние всех health checks в реальном времени.

Этап 5: Тестирование 100% coverage и документирование (30–45 минут)

Действия

1. Проверьте покрытие: убедитесь, что для каждого компонента есть как минимум liveness check. Используйте скрипт, который итерируется по списку компонентов и проверяет наличие метрики probe_success{target="..."} или health_status{} в Prometheus.
2. Протестируйте сценарии отказа:
   • Остановите Redis: docker stop redis. Убедитесь, что метрика probe_success стала 0 и через 1 минуту сработал алерт.
   • Заставьте LLM API отвечать с ошибкой (например, эмулируйте недоступность модели).
3. Задокументируйте в одном файле HEALTH.md:
   • Список всех health checks и их эндпоинты/скрипты.
   • Параметры каждого check (интервал, таймаут, количество ретраев).
   • Инструкцию по добавлению нового компонента.

Ожидаемый результат этапа Подтверждение 100% coverage (скрипт или дашборд показывает, что все компоненты покрыты). Документация в репозитории.

5. Критерии приемки (Definition of Done)

• Для каждого компонента (LLM API, Vector DB, Embedding API, Redis) настроен автоматический health check.
• Все health checks работают циклически (интервал ≤ 30 сек для liveness, ≤ 60 сек для readiness).
• Метрики health собираются Prometheus и отображаются в дашборде Grafana.
• Алерт-правила настроены для критических компонентов (liveness failure в течение 1 минуты → критический алерт).
• Покрытие health checks = 100% (нет ни одного компонента без check).
• Написан скрипт, который проверяет coverage автоматически (например, парсит конфиг и сверяет с логами Prometheus).
• Документация HEALTH.md содержит схему, примеры и процедуру добавления новых checks.
• Тестирование на остановку компонента: после остановки компонента алерт срабатывает не позднее чем через 2 минуты, а дашборд показывает красный статус.

6. Ожидаемый результат

• Файл конфигурации prometheus.yml и alert.rules.yml — готовые к применению в production.
• Дашборд Grafana экспортированный JSON (например, health-dashboard.json).
• Скрипты health checks redis_health.py, embedding_health.py (если не встроенные).
• Документация HEALTH.md с описанием архитектуры мониторинга.
• Docker Compose / Kubernetes манифесты с секциями healthcheck или livenessProbe/readinessProbe.
• Дополнительно инструкция по добавлению нового компонента в систему health checks.

7. Возможные сложности и их решение

8. Бюджет времени (оценка)

Примечание: если Prometheus и Grafana уже развёрнуты, время сократится до 3–4 часов. Для первого выполнения рассчитывайте полный бюджет.

9. Связанные вопросы из базы знаний

10. Чек-лист самопроверки

• Я определил критерии health (liveness + readiness) для каждого из четырёх компонентов.
• Я реализовал или настроил хотя бы один способ автоматической проверки для каждого компонента.
• Я интегрировал эти checks с Prometheus (прямо или через blackbox exporter).
• Я создал алерт-правила, которые срабатывают при падении критического компонента.
• Я разработал дашборд в Grafana, где за 5 секунд видно состояние всех компонентов.
• Я написал документацию HEALTH.md с описанием всех checks и их параметров.
• Я протестировал сценарий отказа (остановил один компонент) и убедился, что алерт пришёл в течение 2 минут.