FastAPI with Golden Signals Monitoring

FastAPI приложение с полным мониторингом на основе четырех Golden Signals: Traffic, Latency, Errors, и Saturation.

О проекте

Этот проект демонстрирует:

• REST API на FastAPI с автоматическим сбором метрик
• Мониторинг по методологии Four Golden Signals от Google SRE
• Полную настройку Prometheus для сбора метрик
• Готовый дашборд в Grafana для визуализации всех ключевых показателей
• Containerized архитектуру с Docker Compose

Что такое Golden Signals?

Four Golden Signals - это четыре ключевых метрики для мониторинга любого сервиса, описанные в книге Google Site Reliability Engineering:

1. Latency - время отклика на запросы
2. Traffic - объем нагрузки на систему
3. Errors - частота ошибок
4. Saturation - степень использования ресурсов

Компоненты стека

• FastAPI (Python 3.11) - REST API приложение с метриками
• Prometheus - система мониторинга и time-series база данных
• Grafana - платформа для визуализации метрик

Структура проекта

.
├── app/                    # FastAPI приложение
│   ├── main.py            # Основной код API
│   └── requirements.txt   # Python зависимости
├── config/                # Конфигурационные файлы
│   ├── prometheus.yml     # Конфигурация Prometheus
│   └── grafana/           # Настройки Grafana и дашборды
├── k6/                    # K6 нагрузочные тесты
│   ├── load-test.js       # Одноразовый тест
│   ├── load-continuous.js # Непрерывная нагрузка ~10 RPS
│   ├── load-light.js      # Легкая нагрузка ~5 RPS
│   └── load-heavy.js      # Тяжелая нагрузка ~20 RPS
├── docker-compose.yml     # Оркестрация контейнеров
├── Dockerfile             # Образ FastAPI
└── Makefile              # Команды для управления

Требования

• Docker и Docker Compose
• Порты 3000, 8000, 9090 должны быть свободны
• K6 (для нагрузочного тестирования)

Установка K6

macOS (Homebrew):

brew install k6

Linux:

# Debian/Ubuntu
sudo gpg -k
sudo gpg --no-default-keyring --keyring /usr/share/keyrings/k6-archive-keyring.gpg --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys C5AD17C747E3415A3642D57D77C6C491D6AC1D69
echo "deb [signed-by=/usr/share/keyrings/k6-archive-keyring.gpg] https://dl.k6.io/deb stable main" | sudo tee /etc/apt/sources.list.d/k6.list
sudo apt-get update
sudo apt-get install k6

Windows:

choco install k6

Или скачайте с официального сайта: https://k6.io/docs/get-started/installation/

Быстрый старт

1. Запуск всех сервисов

Используйте Makefile:

make up

Или напрямую через Docker Compose:

docker-compose up -d --build

2. Проверка статуса

make status

Все контейнеры должны быть в состоянии "healthy" или "running".

3. Открыть интерфейсы

• FastAPI Swagger UI: http://localhost:8000/docs

  • Интерактивная документация API
  • Тестирование endpoints прямо в браузере

• Prometheus: http://localhost:9090

  • Web UI для просмотра метрик
  • PromQL запросы

• Grafana: http://localhost:3000

  • Логин: admin
  • Пароль: admin
  • Дашборд: "FastAPI Golden Signals Dashboard" (автоматически создается)

4. Генерация тестовой нагрузки (K6)

Одноразовый тест:

make load-test

Выполняет набор запросов ко всем endpoints для быстрой проверки метрик.

Непрерывная нагрузка (~10 RPS):

make load-continuous

Распределение: 50% fast, 20% slow, 30% errors. Нажмите Ctrl+C для остановки.

Легкая нагрузка (~5 RPS):

make load-light

Распределение: 60% fast, 20% slow, 20% errors. Нажмите Ctrl+C для остановки.

Тяжелая нагрузка (~20 RPS):

make load-heavy

Распределение: 50% fast, 20% slow, 30% errors. Нажмите Ctrl+C для остановки.

Все K6 скрипты находятся в папке k6/ и могут быть запущены напрямую:

k6 run k6/load-test.js

API Endpoints

• GET / - Корневой endpoint
• GET /health - Проверка здоровья
• GET /fast - Быстрый endpoint (для тестирования latency)
• GET /slow - Медленный endpoint (0.5-2 сек задержка)
• GET /error - Endpoint с рандомными ошибками (30% вероятность)
• GET /errors - Endpoint, который ВСЕГДА возвращает 5xx ошибки (500/502/503/504) с разной latency (0.1-3 сек) - идеален для тестирования дашбордов
• GET /metrics - Prometheus метрики

Golden Signals

1. Traffic (Трафик)

Количество запросов в секунду к каждому endpoint.

Метрика: http_requests_total

2. Latency (Задержка)

Время ответа API (p50, p95, p99 перцентили).

Метрика: http_request_duration_seconds

3. Errors (Ошибки)

Процент запросов с HTTP статусом >= 400.

Метрика: http_errors_total

4. Saturation (Насыщенность)

Использование системных ресурсов: CPU, память, диск.

Метрики:

• system_cpu_usage_percent
• system_memory_usage_percent
• system_disk_usage_percent

Как использовать Grafana Dashboard

1. Откройте http://localhost:3000
2. Войдите (admin/admin)
3. Перейдите в Dashboards → FastAPI Golden Signals Dashboard
4. Вы увидите 4 основных панели:
   • Traffic: Количество запросов в секунду по endpoints
   • Latency: Перцентили времени ответа (p50, p95, p99)
   • Errors: Процент ошибочных запросов
   • Saturation: Использование CPU, памяти и диска

Makefile команды

Команда	Описание
make up	Запустить все сервисы
make down	Остановить все сервисы
make restart	Перезапустить все сервисы
make logs	Показать логи всех сервисов
make logs-api	Показать логи только FastAPI
make status	Показать статус контейнеров
make load-test	Сгенерировать тестовую нагрузку
make clean	Удалить контейнеры и volumes
make rebuild	Пересобрать и перезапустить

Тестирование метрик вручную

# Нормальные запросы
curl http://localhost:8000/
curl http://localhost:8000/health

# Быстрые запросы (малая latency)
for i in {1..100}; do curl -s http://localhost:8000/fast; done

# Медленные запросы (высокая latency)
for i in {1..10}; do curl -s http://localhost:8000/slow; done

# Запросы с ошибками (увеличение error rate)
for i in {1..20}; do curl -s http://localhost:8000/error; done

# Просмотр raw метрик
curl http://localhost:8000/metrics

Доступ из интернета

Порты для внешнего доступа

Все сервисы настроены на прослушивание на всех интерфейсах (0.0.0.0):

• Grafana: порт 3000 - главный интерфейс мониторинга
• FastAPI: порт 8000 - API endpoints и метрики
• Prometheus: порт 9090 - Web UI (опционально)

Настройка для продакшена

При развертывании на сервере для доступа из интернета:

1. Firewall/Security Groups: Откройте необходимые порты

   # Пример для UFW (Ubuntu)
   sudo ufw allow 3000/tcp  # Grafana
   sudo ufw allow 8000/tcp  # FastAPI

2. Nginx Reverse Proxy (рекомендуется):

   server {
       listen 80;
       server_name your-domain.com;
   
       location / {
           proxy_pass http://localhost:3000;
           proxy_set_header Host $host;
           proxy_set_header X-Real-IP $remote_addr;
       }
   }

3. HTTPS с Let's Encrypt:

   sudo certbot --nginx -d your-domain.com

4. Изменить пароль Grafana:

   • Войдите с admin/admin
   • Grafana попросит сменить пароль при первом входе
   • Или измените в docker-compose.yml переменные окружения

Безопасность

ВАЖНО: Стандартные логин/пароль Grafana - admin/admin

Для production использования:

• Смените пароль администратора
• Используйте HTTPS
• Настройте firewall
• Рассмотрите использование OAuth/LDAP для аутентификации
• Ограничьте доступ к Prometheus (порт 9090) только для внутренней сети

Разработка

Локальный запуск без Docker

# Установка зависимостей
pip install -r requirements.txt

# Запуск приложения
python app.py

Приложение будет доступно на http://localhost:8000

Структура проекта

.
├── app.py                          # FastAPI приложение
├── requirements.txt                # Python зависимости
├── Dockerfile                      # Docker образ для FastAPI
├── docker-compose.yml              # Docker Compose конфигурация
├── prometheus.yml                  # Конфигурация Prometheus
└── grafana/
    └── provisioning/
        ├── datasources/
        │   └── datasource.yml      # Prometheus datasource
        └── dashboards/
            ├── dashboard.yml       # Provisioning конфигурация
            └── golden-signals-dashboard.json  # Дашборд