Введение
После того как ваше веб-приложение попадает в продакшн, самый важный вопрос — а как оно работает прямо сейчас? Логи дают ответ постфактум, но хочется видеть проблемы до того, как пользователи начнут жаловаться.
В этой статье я расскажу, как построил полноценную систему мониторинга для Peakline — FastAPI приложения для анализа Strava данных, обрабатывающего тысячи запросов в день от спортсменов по всему миру.
Что внутри:
Архитектура метрик (HTTP, API, бизнес-метрики)
Настройка Prometheus + Grafana с нуля
50+ production-ready метрик
Продвинутые PromQL запросы
Реактивные дашборды
Best practices и подводные камни
Архитектура: три уровня мониторинга
Современная система мониторинга — это не просто "поставил Grafana и смотрю графики". Это продуманная архитектура из нескольких слоев:
┌─────────────────────────────────────────────────┐ │ FastAPI Application │ │ ├── HTTP Middleware (автосбор метрик) │ │ ├── Business Logic (бизнес-метрики) │ │ └── /metrics endpoint (Prometheus format) │ └──────────────────┬──────────────────────────────┘ │ scrape every 5s ┌──────────────────▼──────────────────────────────┐ │ Prometheus │ │ ├── Time Series Database (TSDB) │ │ ├── Storage retention: 200h │ │ └── PromQL Engine │ └──────────────────┬──────────────────────────────┘ │ query data ┌──────────────────▼──────────────────────────────┐ │ Grafana │ │ ├── Dashboards │ │ ├── Alerting │ │ └── Visualization │ └─────────────────────────────────────────────────┘
Почему именно эта связка?
Prometheus — de-facto стандарт в мире метрик. Pull-модель, мощный язык запросов PromQL, отличная интеграция с Kubernetes.
Grafana — лучший инструмент визуализации. Красивые дашборды, алерты, templating, rich UI.
FastAPI — асинхронный Python-фреймворк с нативной поддержкой метрик через prometheus_client.
Настройка базовой инфраструктуры
Docker Compose: быстрый старт за 5 минут
Первым делом поднимаем Prometheus и Grafana в Docker:
# docker-compose.yml version: '3.8' services: prometheus: image: prom/prometheus:latest container_name: prometheus ports: - "9090:9090" volumes: - ./monitoring/prometheus.yml:/etc/prometheus/prometheus.yml - prometheus_data:/prometheus command: - '--config.file=/etc/prometheus/prometheus.yml' - '--storage.tsdb.path=/prometheus' - '--storage.tsdb.retention.time=200h' # 8+ дней истории - '--web.enable-lifecycle' networks: - monitoring extra_hosts: - "host.docker.internal:host-gateway" # Для доступа к хосту grafana: image: grafana/grafana:latest container_name: grafana ports: - "3000:3000" environment: - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD} # Используйте .env! - GF_SERVER_ROOT_URL=/grafana # Для nginx reverse proxy volumes: - grafana_data:/var/lib/grafana - ./monitoring/grafana/provisioning:/etc/grafana/provisioning depends_on: - prometheus networks: - monitoring volumes: prometheus_data: grafana_data: networks: monitoring: driver: bridge
Ключевые моменты:
storage.tsdb.retention.time=200h— храним метрики 8+ дней (для недельного анализа)extra_hosts: host.docker.internal— позволяет Prometheus достучаться до приложения на хостеVolumes для персистентности данных
Конфигурация Prometheus
# monitoring/prometheus.yml global: scrape_interval: 15s # Как часто собирать метрики evaluation_interval: 15s # Как часто проверять алерты scrape_configs: - job_name: 'prometheus' static_configs: - targets: ['localhost:9090'] - job_name: 'webapp' static_configs: - targets: ['host.docker.internal:8000'] # Порт вашего приложения scrape_interval: 5s # Более частый сбор для веб-приложения metrics_path: /metrics
Важно: scrape_interval: 5s для веб-приложения — это баланс между актуальностью данных и нагрузкой на систему. В production обычно 15-30s.
Провиженинг Grafana datasource
Чтобы не настраивать Prometheus в Grafana руками, используем provisioning:
# monitoring/grafana/provisioning/datasources/prometheus.yml apiVersion: 1 datasources: - name: Prometheus type: prometheus access: proxy url: http://prometheus:9090 isDefault: true editable: true
Теперь при запуске Grafana автоматически подключится к Prometheus.
docker-compose up -d
Уровень 1: HTTP метрики
Самый базовый, но критически важный слой — мониторинг HTTP запросов. Middleware автоматически собирает метрики всех HTTP запросов.
Инициализация метрик
# webapp/main.py from prometheus_client import Counter, Histogram, CollectorRegistry, generate_latest, CONTENT_TYPE_LATEST from fastapi import FastAPI, Request from fastapi.responses import PlainTextResponse import time app = FastAPI(title="Peakline", version="2.0.0") # Создаем отдельный registry для изоляции метрик registry = CollectorRegistry() # Counter: монотонно растущее значение (кол-во запросов) http_requests_total = Counter( 'http_requests_total', 'Total number of HTTP requests', ['method', 'endpoint', 'status_code'], # Labels для группировки registry=registry ) # Histogram: распределение значений (время выполнения) http_request_duration_seconds = Histogram( 'http_request_duration_seconds', 'HTTP request duration in seconds', ['method', 'endpoint'], registry=registry ) # Счетчики API вызовов api_calls_total = Counter( 'api_calls_total', 'Total number of API calls by type', ['api_type'], registry=registry ) # Отдельные счетчики для ошибок http_errors_4xx_total = Counter( 'http_errors_4xx_total', 'Total number of 4xx HTTP errors', ['endpoint', 'status_code'], registry=registry ) http_errors_5xx_total = Counter( 'http_errors_5xx_total', 'Total number of 5xx HTTP errors', ['endpoint', 'status_code'], registry=registry )
Middleware для автоматического сбора
Магия происходит в middleware — он оборачивает каждый запрос:
@app.middleware("http") async def metrics_middleware(request: Request, call_next): start_time = time.time() # Выполняем запрос response = await call_next(request) duration = time.time() - start_time # Нормализация пути: /api/activities/12345 → /api/activities/{id} path = request.url.path if path.startswith('/api/'): parts = path.split('/') if len(parts) > 3 and parts[3].isdigit(): parts[3] = '{id}' path = '/'.join(parts) # Записываем метрики http_requests_total.labels( method=request.method, endpoint=path, status_code=str(response.status_code) ).inc() http_request_duration_seconds.labels( method=request.method, endpoint=path ).observe(duration) # Трекинг API вызовов if path.startswith('/api/'): api_type = path.split('/')[2] if len(path.split('/')) > 2 else 'unknown' api_calls_total.labels(api_type=api_type).inc() # Отдельный подсчет ошибок status_code = response.status_code if 400 <= status_code < 500: http_errors_4xx_total.labels(endpoint=path, status_code=str(status_code)).inc() elif status_code >= 500: http_errors_5xx_total.labels(endpoint=path, status_code=str(status_code)).inc() return response
Ключевые техники:
Нормализация путей — критически важно! Без этого получите тысячи уникальных метрик для
/api/activities/1,/api/activities/2, etc.Labels — позволяют фильтровать и группировать метрики в PromQL
Отдельные счетчики для ошибок — упрощают написание алертов
Endpoint для метрик
@app.get("/metrics") async def metrics(): """Prometheus metrics endpoint""" return PlainTextResponse( generate_latest(registry), media_type=CONTENT_TYPE_LATEST )
Теперь Prometheus может собирать метрики с http://localhost:2121/metrics.
Что мы получаем в Prometheus?
# Формат метрик в /metrics endpoint: http_requests_total{method="GET",endpoint="/api/activities",status_code="200"} 1543 http_requests_total{method="POST",endpoint="/api/activities",status_code="201"} 89 http_request_duration_seconds_bucket{method="GET",endpoint="/api/activities",le="0.1"} 1234
Уровень 2: Внешние API метрики
Веб-приложение часто интегрируется с внешними API (Strava, Stripe, AWS, etc.). Важно отслеживать не только свои запросы, но и зависимости.
Метрики для внешних API
# Strava API metrics strava_api_calls_total = Counter( 'strava_api_calls_total', 'Total number of Strava API calls by endpoint type', ['endpoint_type'], registry=registry ) strava_api_errors_total = Counter( 'strava_api_errors_total', 'Total number of Strava API errors by endpoint type', ['endpoint_type'], registry=registry ) strava_api_latency_seconds = Histogram( 'strava_api_latency_seconds', 'Strava API call latency in seconds', ['endpoint_type'], registry=registry )
Helper для трекинга API вызовов
Вместо дублирования кода в каждом месте вызова API, создаем универсальную обертку:
async def track_strava_api_call(endpoint_type: str, api_call_func, *args, **kwargs): """ Универсальная обертка для трекинга API вызовов Usage: result = await track_strava_api_call( 'athlete_activities', client.get_athlete_activities, athlete_id=123 ) """ start_time = time.time() try: # Инкрементируем счетчик вызовов strava_api_calls_total.labels(endpoint_type=endpoint_type).inc() # Выполняем API вызов result = await api_call_func(*args, **kwargs) # Записываем latency duration = time.time() - start_time strava_api_latency_seconds.labels(endpoint_type=endpoint_type).observe(duration) # Проверяем на ошибки API (статус >= 400) if isinstance(result, Exception) or (hasattr(result, 'status') and result.status >= 400): strava_api_errors_total.labels(endpoint_type=endpoint_type).inc() return result except Exception as e: # Записываем latency и ошибку duration = time.time() - start_time strava_api_latency_seconds.labels(endpoint_type=endpoint_type).observe(duration) strava_api_errors_total.labels(endpoint_type=endpoint_type).inc() raise e
Использование в коде
@app.get("/api/activities") async def get_activities(athlete_id: int): # Вместо прямого вызова API: # activities = await strava_client.get_athlete_activities(athlete_id) # Используем обертку с трекингом: activities = await track_strava_api_call( 'athlete_activities', strava_client.get_athlete_activities, athlete_id=athlete_id ) return activities
Теперь мы видим:
Сколько вызовов к каждому endpoint Strava API
Сколько из них вернули ошибки
Какая latency у каждого типа вызовов
Уровень 3: Бизнес-метрики
Это самая ценная часть мониторинга — метрики, которые отражают реальное использование приложения.
Виды бизнес-метрик
# === Аутентификация === user_logins_total = Counter( 'user_logins_total', 'Total number of user logins', registry=registry ) user_registrations_total = Counter( 'user_registrations_total', 'Total number of new user registrations', registry=registry ) user_deletions_total = Counter( 'user_deletions_total', 'Total number of user deletions', registry=registry ) # === Файловые операции === fit_downloads_total = Counter( 'fit_downloads_total', 'Total number of FIT file downloads', registry=registry ) gpx_downloads_total = Counter( 'gpx_downloads_total', 'Total number of GPX file downloads', registry=registry ) gpx_uploads_total = Counter( 'gpx_uploads_total', 'Total number of GPX file uploads', registry=registry ) # === Пользовательские действия === settings_updates_total = Counter( 'settings_updates_total', 'Total number of user settings updates', registry=registry ) idea_creations_total = Counter( 'idea_creations_total', 'Total number of feature requests', registry=registry ) idea_votes_total = Counter( 'idea_votes_total', 'Total number of votes for ideas', registry=registry ) # === Отчеты === manual_reports_total = Counter( 'manual_reports_total', 'Total number of manually created reports', registry=registry ) auto_reports_total = Counter( 'auto_reports_total', 'Total number of automatically created reports', registry=registry ) failed_reports_total = Counter( 'failed_reports_total', 'Total number of failed report creation attempts', registry=registry )
Инкрементирование в коде
@app.post("/api/auth/login") async def login(credentials: LoginCredentials): user = await authenticate_user(credentials) if user: # Инкрементируем счетчик успешных логинов user_logins_total.inc() return {"token": generate_token(user)} return {"error": "Invalid credentials"} @app.post("/api/activities/report") async def create_report(activity_id: int, is_auto: bool = False): try: report = await generate_activity_report(activity_id) # Разные счетчики для ручных и автоматических отчетов if is_auto: auto_reports_total.inc() else: manual_reports_total.inc() return report except Exception as e: failed_reports_total.inc() raise e
Уровень 4: Производительность и кэширование
Метрики кэша
Кэш — критически важная часть производительности. Нужно отслеживать hit rate:
cache_hits_total = Counter( 'cache_hits_total', 'Total number of cache hits', ['cache_type'], registry=registry ) cache_misses_total = Counter( 'cache_misses_total', 'Total number of cache misses', ['cache_type'], registry=registry ) # В коде кэширования: async def get_from_cache(key: str, cache_type: str = 'generic'): value = await cache.get(key) if value is not None: cache_hits_total.labels(cache_type=cache_type).inc() return value else: cache_misses_total.labels(cache_type=cache_type).inc() return None
Метрики фоновых задач
Если у вас есть background tasks (Celery, APScheduler), отслеживайте их:
background_task_duration_seconds = Histogram( 'background_task_duration_seconds', 'Background task execution time', ['task_type'], registry=registry ) async def run_background_task(task_type: str, task_func, *args, **kwargs): start_time = time.time() try: result = await task_func(*args, **kwargs) return result finally: duration = time.time() - start_time background_task_duration_seconds.labels(task_type=task_type).observe(duration)
PromQL: язык запросов метрик
Prometheus использует собственный язык запросов — PromQL. Это не SQL, но очень мощно.
Базовые запросы
# 1. Просто получить метрику (instant vector) http_requests_total # 2. Фильтрация по labels http_requests_total{method="GET"} http_requests_total{status_code="200"} http_requests_total{method="GET", endpoint="/api/activities"} # 3. Регулярные выражения в labels http_requests_total{status_code=~"5.."} # Все 5xx ошибки http_requests_total{endpoint=~"/api/.*"} # Все API эндпоинты # 4. Временной интервал (range vector) http_requests_total[5m] # Данные за последние 5 минут
Rate и irate: скорость изменения
Counter постоянно растет, но нам нужна скорость изменения — RPS (requests per second):
# Rate - средняя скорость за интервал rate(http_requests_total[5m]) # irate - мгновенная скорость (между последними двумя точками) irate(http_requests_total[5m])
Когда что использовать:
rate()— для алертов и графиков тренда (сглаживает всплески)irate()— для детального анализа (показывает пики)
Агрегация с sum, avg, max
# Общий RPS приложения sum(rate(http_requests_total[5m])) # RPS по методам sum(rate(http_requests_total[5m])) by (method) # RPS по endpoint'ам, отсортированный sort_desc(sum(rate(http_requests_total[5m])) by (endpoint)) # Средняя latency avg(rate(http_request_duration_seconds_sum[5m]) / rate(http_request_duration_seconds_count[5m]))
Histogram и percentiles
Для Histogram метрик (latency, duration) используем histogram_quantile:
# P50 (медиана) latency histogram_quantile(0.5, rate(http_request_duration_seconds_bucket[5m])) # P95 latency histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) # P99 latency (99% запросов быстрее этого) histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m])) # P95 по каждому endpoint'у histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) by (endpoint)
Сложные запросы
1. Success Rate (процент успешных запросов)
( sum(rate(http_requests_total{status_code=~"2.."}[5m])) / sum(rate(http_requests_total[5m])) ) * 100
2. Error Rate (процент ошибок)
( sum(rate(http_requests_total{status_code=~"4..|5.."}[5m])) / sum(rate(http_requests_total[5m])) ) * 100
3. Cache Hit Rate
( sum(rate(cache_hits_total[5m])) / (sum(rate(cache_hits_total[5m])) + sum(rate(cache_misses_total[5m]))) ) * 100
4. Top-5 самых медленных endpoints
topk(5, histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]) ) by (endpoint) )
5. API Health Score (0-100)
( ( sum(rate(strava_api_calls_total[5m])) - sum(rate(strava_api_errors_total[5m])) ) / sum(rate(strava_api_calls_total[5m])) ) * 100
Grafana Dashboards: визуализация
Теперь самое интересное — превращаем сырые метрики в красивые и информативные дашборды.
Dashboard 1: HTTP & Performance
Панель 1: Request Rate
sum(rate(http_requests_total[5m]))
Тип: Time series
Цвет: Синий градиент
Unit: requests/sec
Легенда: Total RPS
Панель 2: Success Rate
( sum(rate(http_requests_total{status_code=~"2.."}[5m])) / sum(rate(http_requests_total[5m])) ) * 100
Тип: Stat
Цвет: Зеленый если > 95%, желтый если > 90%, красный если < 90%
Unit: percent (0-100)
Значение: Текущее (last)
Панель 3: Response Time (P50, P95, P99)
# P50 histogram_quantile(0.5, rate(http_request_duration_seconds_bucket[5m])) # P95 histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) # P99 histogram_quantile(0.99, rate(http_request_duration_seconds_bucket[5m]))
Тип: Time series
Unit: seconds (s)
Легенда: P50, P95, P99
Панель 4: Errors by Type
sum(rate(http_requests_total{status_code=~"4.."}[5m])) by (status_code) sum(rate(http_requests_total{status_code=~"5.."}[5m])) by (status_code)
Тип: Bar chart
Colors: Желтый (4xx), Красный (5xx)
Панель 5: Request Rate by Endpoint
sort_desc(sum(rate(http_requests_total[5m])) by (endpoint))
Тип: Bar chart
Limit: Top 10
Dashboard 2: Business Metrics
Этот дашборд показывает реальное использование продукта — что пользователи делают и как часто.
Панель 1: User Activity (24h)
# Логины increase(user_logins_total[24h]) # Регистрации increase(user_registrations_total[24h]) # Удаления increase(user_deletions_total[24h])
Тип: Stat
Layout: Horizontal
Панель 2: Downloads by Type
sum(rate({__name__=~".*_downloads_total"}[5m])) by (__name__)
Тип: Pie chart
Легенда справа
Панель 3: Feature Usage Timeline
rate(gpx_fixer_usage_total[5m]) rate(search_usage_total[5m]) rate(manual_reports_total[5m])
Тип: Time series
Stacking: Normal
Dashboard 3: External API
Критически важно мониторить зависимости от внешних сервисов — они могут стать узким местом.
Панель 1: API Health Score
( sum(rate(strava_api_calls_total[5m])) - sum(rate(strava_api_errors_total[5m])) ) / sum(rate(strava_api_calls_total[5m])) * 100
Тип: Gauge
Min: 0, Max: 100
Thresholds: 95 (зеленый), 90 (желтый), 0 (красный)
Панель 2: API Latency by Endpoint
histogram_quantile(0.95, rate(strava_api_latency_seconds_bucket[5m])) by (endpoint_type)
Тип: Bar chart
Sort: Descending
Панель 3: Error Rate by Endpoint
sum(rate(strava_api_errors_total[5m])) by (endpoint_type)
Тип: Bar chart
Color: Красный
Variables: динамические дашборды
Grafana поддерживает переменные для интерактивных дашбордов:
Создание переменной
Dashboard Settings → Variables → Add variable
Name:
endpointType: Query
Query:
label_values(http_requests_total, endpoint)
Использование в панелях
# Фильтр по выбранному endpoint sum(rate(http_requests_total{endpoint="$endpoint"}[5m])) # Multi-select sum(rate(http_requests_total{endpoint=~"$endpoint"}[5m])) by (endpoint)
Полезные переменные
# Временной интервал Variable: interval Type: Interval Values: 1m,5m,10m,30m,1h # Метод HTTP Variable: method Query: label_values(http_requests_total, method) # Статус код Variable: status_code Query: label_values(http_requests_total, status_code)
Alerting: реактивность системы
Мониторинг без алертов — как автомобиль без тормозов. Настраиваем умные алерты.
Grafana Alerting
Alert 1: High Error Rate
( sum(rate(http_requests_total{status_code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) ) * 100 > 1
Condition:
> 1(больше 1% ошибок)For: 5m (в течение 5 минут)
Severity: Critical
Notification: Slack, Email, Telegram
Alert 2: High Latency
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) > 2
Condition: P95 > 2 секунд
For: 10m
Severity: Warning
Alert 3: External API Down
sum(rate(strava_api_errors_total[5m])) / sum(rate(strava_api_calls_total[5m])) > 0.5
Condition: Больше 50% ошибок API
For: 2m
Severity: Critical
Alert 4: No Data
absent_over_time(http_requests_total[10m])
Condition: Нет метрик 10 минут
Severity: Critical
Означает: приложение упало или Prometheus не может собрать метрики
Notification Channels
# grafana/provisioning/notifiers/slack.yml notifiers: - name: Slack type: slack uid: slack-notifications settings: url: https://hooks.slack.com/services/YOUR/WEBHOOK/URL recipient: '#monitoring' mentionChannel: 'here'
Best Practices: боевой опыт
1. Labels: не переборщите
❌ Плохо:
# Слишком детализированные labels = cardinality explosion http_requests_total.labels( method=request.method, endpoint=request.url.path, # Каждый уникальный URL! user_id=str(user.id), # Тысячи пользователей! timestamp=str(time.time()) # Бесконечные значения! ).inc()
✅ Хорошо:
# Нормализованные endpoint'ы + ограниченный набор labels http_requests_total.labels( method=request.method, endpoint=normalize_path(request.url.path), # /api/users/{id} status_code=str(response.status_code) ).inc()
Правило: High-cardinality данные (user_id, timestamps, unique IDs) НЕ должны быть labels.
2. Naming Convention
Следуйте Prometheus naming conventions:
# Хорошие имена: http_requests_total # __ strava_api_latency_seconds # Единица измерения в имени cache_hits_total # Понятно, что это Counter # Плохие имена: RequestCount # Не CamelCase api-latency # Не используйте дефисы request_time # Не указана единица измерения
3. Rate() интервал
Интервал rate() должен быть минимум в 4 раза больше scrape_interval:
# Если scrape_interval = 15s rate(http_requests_total[1m]) # 4x = 60s ✅ rate(http_requests_total[30s]) # 2x = плохая точность ❌
4. Histogram buckets
Правильные buckets критичны для точных percentiles:
# По умолчанию (плохо для latency): Histogram('latency_seconds', 'Latency') # [.005, .01, .025, .05, .1, ...] # Кастомные buckets для web latency: Histogram( 'http_request_duration_seconds', 'Request latency', buckets=[.001, .005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10] )
Принцип: Buckets должны покрывать типичный диапазон значений.
5. Стоимость метрик
Каждая метрика стоит памяти. Считаем:
Memory = Series count × (~3KB per series) Series = Metric × Label combinations
Пример:
# 1 метрика × 5 methods × 20 endpoints × 15 status codes = 1,500 series http_requests_total{method, endpoint, status_code} # 1,500 × 3KB = ~4.5MB для одной метрики!
Совет: Регулярно проверяйте cardinality:
# Топ метрик по cardinality topk(10, count by (__name__)({__name__=~".+"}))
6. Тестирование в dev
Не запускайте метрики только в production:
# .env PROMETHEUS_ENABLED=true # В dev тоже включаем # В коде if os.getenv('PROMETHEUS_ENABLED', 'false') == 'true': setup_prometheus_metrics()
Запускайте нагрузочные тесты с включенными метриками:
# Локальный Prometheus + Grafana docker-compose up -d # Нагрузочный тест locust -f load_test.py --host=http://localhost:2121
Смотрите метрики в реальном времени → находите bottlenecks.
7. Документируйте метрики
Создайте README с описанием всех метрик:
# Metrics Documentation ## HTTP Metrics ### `http_requests_total` - **Type:** Counter - **Labels:** method, endpoint, status_code - **Description:** Total HTTP requests - **Dashboard:** Main → HTTP Performance - **Alert:** High error rate if 5xx > 1% ### `http_request_duration_seconds` - **Type:** Histogram - **Labels:** method, endpoint - **Buckets:** [.001, .005, .01, .025, .05, .1, .25, .5, 1, 2.5, 5, 10] - **Description:** Request latency distribution - **Dashboard:** Main → Response Time P95
Production Checklist
Перед запуском в production проверьте:
[ ] Retention policy настроен (
storage.tsdb.retention.time)[ ] Disk space мониторится (Prometheus может занять много места)
[ ] Backups настроены для Grafana dashboards
[ ] Алерты протестированы (создайте искусственную ошибку)
[ ] Notification channels работают (отправьте тестовый алерт)
[ ] Access control настроен (не оставляйте Grafana с admin/admin!)
[ ] HTTPS настроен для Grafana (через nginx reverse proxy)
[ ] Cardinality проверен (
topk(10, count by (__name__)({__name__=~".+"})))[ ] Документация создана (какая метрика за что отвечает)
[ ] On-call process определен (кто получает алерты и что делать)
Реальный кейс: находим проблему
Представим: пользователи жалуются на медленную работу. Вот как мониторинг помог найти и решить проблему за считанные минуты.
Шаг 1: Открываем Grafana → HTTP Performance Dashboard
histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m]))
Видим: P95 latency выросла с 0.2s до 3s.
Шаг 2: Смотрим latency по endpoint'ам
topk(5, histogram_quantile(0.95, rate(http_request_duration_seconds_bucket[5m])) by (endpoint))
Находим: /api/activities — 5 секунд!
Шаг 3: Проверяем внешние API
histogram_quantile(0.95, rate(external_api_latency_seconds_bucket[5m])) by (endpoint_type)
External API athlete_activities — 4.8 секунд. Вот проблема!
Шаг 4: Смотрим error rate
rate(external_api_errors_total{endpoint_type="athlete_activities"}[5m])
Ошибок нет, просто медленно. Значит, проблема не на нашей стороне — внешний сервис тормозит.
Решение:
Добавляем агрессивное кэширование для внешнего API (TTL 5 минут)
Настраиваем алерт на latency > 2s
Добавляем timeout на запросы
Шаг 5: После деплоя проверяем
# Cache hit rate (cache_hits_total / (cache_hits_total + cache_misses_total)) * 100
Hit rate 85% → latency упала до 0.3s. Победа! 🎉
Что дальше?
Вы построили production-ready систему мониторинга. Но это только начало:
Следующие шаги:
Distributed Tracing — добавьте Jaeger/Tempo для трейсинга запросов
Logging — интегрируйте Loki для централизованных логов
Custom Dashboards — создайте дашборды для бизнеса (не только DevOps)
SLO/SLI — определите Service Level Objectives
Anomaly Detection — используйте машинное обучение для детекции аномалий
Cost Monitoring — добавьте метрики затрат (AWS CloudWatch, etc.)
Полезные ресурсы:
Заключение
Система мониторинга — это не "поставил и забыл". Это живой организм, который нужно развивать вместе с приложением. Но базовая архитектура, которую мы построили, масштабируется от стартапа до enterprise.
Ключевые выводы:
Три уровня метрик: HTTP (инфраструктура) → API (зависимости) → Business (продукт)
Middleware автоматизирует сбор базовых метрик
PromQL мощный — изучайте постепенно
Labels важны — но не переборщите с cardinality
Алерты критичны — мониторинг без алертов бесполезен
Документируйте — через полгода вы забудете, что значит метрика
foo_bar_total
Мониторинг — это культура, а не инструмент. Начните с простого, итерируйте, улучшайте. И ваше приложение будет работать стабильно, а вы будете спать спокойно 😴
О проекте Peakline
Эта система мониторинга разработана для Peakline — веб-приложения для анализа Strava активностей. Peakline предоставляет спортсменам:
Детальный анализ сегментов с интерактивными картами
Исторические данные о погоде для каждой активности
Генерацию продвинутых FIT-файлов для виртуальных гонок
Автоматическое исправление ошибок в GPX треках
Планировщик маршрутов
Все эти фичи требуют надежного мониторинга для обеспечения качественного пользовательского опыта.
Вопросы? Пишите в комментариях!
P.S. Если статья была полезна — поделитесь с коллегами, кому может пригодиться.
Об авторе
Solo developer, создающий Peakline — инструменты для спортсменов. Сам спортсмен и энтузиаст, верю в automation, observability и качественный код. В 2025 году продолжаю развивать проект и делиться опытом с сообществом.
