Логування та моніторинг трафіку API Gateway

Ми стикалися з проектами, де прод починає сипати 500-ми через перевантаження одного ендпоінта, а розробники витрачають години на пошук причини за розрізненими логами. Без єдиної точки входу — шлюзу — ви сліпі: не бачите, хто викликає API, з якою затримкою, які роути падають. Налаштування логування та моніторингу трафіку через API Gateway вирішує ці проблеми за кілька днів і дає прозорість усього трафіку. Наш досвід впровадження подібних рішень гарантує стабільність і скорочення часу пошуку інцидентів до 15 хвилин.

Ми інтегруємо у ваш шлюз збір мінімально необхідних полів: request_id (наскрізна трасування), consumer_id (ідентифікація клієнта), method, path, status_code, latency_ms, розміри запитів. Тіло запиту не логуємо за замовчуванням — тільки в дебаг-режимі для вибраних роутів, щоб не світити чутливі дані. Після впровадження одна з команд скоротила час пошуку інцидентів з 2 годин до 15 хвилин.

Які метрики критичні для налагодження API?

Без централізованого збору ви не зможете швидко відповісти на питання: який ендпоінт найповільніший, хто генерує 90% помилок, чому впав upstream. Ми налаштовуємо шлюз так, щоб кожен запит залишав повний цифровий слід:

Кожен запит також збагачується мітками (consumer, route) — це дозволяє будувати зрізи за клієнтами та ендпоінтами.

Ризики логування тіла запиту

У production тіло запиту містить чутливі дані: паролі, токени, PAN-дані. Ми налаштовуємо шлюз так, щоб body логувався тільки для вибраних роутів у дебаг-режимі. У Kong це контролюється флагом dataTraceEnabled, у AWS — окремим конфігом. Якщо потрібно налагодити конкретний запит, вмикаємо логування тіла на 15 хвилин і вимикаємо. Kong documentation recommends enabling body logging only when necessary to avoid data leaks.

Як працює наскрізна трасування з request_id?

request_id — це UUID, який генерується на шлюзі та передається всім бекенд-сервісам через HTTP-заголовок X-Request-ID. Кожен сервіс записує свій request_id у логи, що дозволяє зібрати повну картину виконання одного запиту. Для цього достатньо додати заголовок у всі вихідні виклики — це робиться middleware за годину. Після цього можна побудувати дашборд «шлях запиту», де видно всі виклики між мікросервісами.

Як налаштувати Kong Gateway для збору метрик?

Kong — найпопулярніший self-hosted шлюз. Логування через плагін http-log і метрики через prometheus налаштовуються в одному конфігу:

---
plugins:
  - name: http-log
    config:
      http_endpoint: http://logstash:5044/kong
      method: POST
      timeout: 1000
      keepalive: 1000
      flush_timeout: 2
      retry_count: 10
      queue:
        max_batch_size: 200
        max_coalescing_delay: 1
        max_entries: 10000
  - name: prometheus
    config:
      per_consumer: true
      status_code_metrics: true
      latency_metrics: true
      bandwidth_metrics: true
      upstream_health_metrics: true

Після цього /metrics на Kong Manager віддає всі метрики у форматі Prometheus. Scrape-інтервал — 15 секунд.

Налаштування в AWS API Gateway

В AWS логування налаштовується на рівні Stage через CloudWatch:

{
  "loggingLevel": "INFO",
  "dataTraceEnabled": false,
  "metricsEnabled": true,
  "accessLogDestinationArn": "arn:aws:logs:us-east-1:123456789:log-group:api-gateway-access",
  "accessLogFormat": "{\"requestId\":\"$context.requestId\",\"ip\":\"$context.identity.sourceIp\",\"caller\":\"$context.identity.caller\",\"user\":\"$context.identity.user\",\"requestTime\":\"$context.requestTime\",\"httpMethod\":\"$context.httpMethod\",\"resourcePath\":\"$context.resourcePath\",\"status\":\"$context.status\",\"protocol\":\"$context.protocol\",\"responseLength\":\"$context.responseLength\",\"integrationLatency\":\"$context.integrationLatency\",\"responseLatency\":\"$context.responseLatency\"}"
}

dataTraceEnabled: false — ніколи не вмикати в production, пише тіла запитів. CloudWatch Insights-запит для p95 latency за ендпоінтом:

fields @timestamp, resourcePath, responseLatency | filter status >= 200 | stats pct(responseLatency, 95) as p95 by resourcePath | sort p95 desc | limit 20 

Nginx API Gateway + OpenTelemetry

Якщо gateway на Nginx (nginx-plus або OpenResty), логування налаштовується через log_format:

log_format api_json escape=json '{'
    '"timestamp":"$time_iso8601",'
    '"request_id":"$request_id",'
    '"method":"$request_method",'
    '"path":"$uri",'
    '"status":$status,'
    '"latency_ms":$request_time,'
    '"upstream_latency_ms":"$upstream_response_time",'
    '"bytes_sent":$bytes_sent,'
    '"consumer":"$http_x_consumer_id",'
    '"ip":"$remote_addr"'
  '}';
access_log /var/log/nginx/api_access.log api_json buffer=32k flush=5s;

Для розподіленої трасування використовуйте opentelemetry-nginx-module — ми підключаємо його при необхідності.

Який стек візуалізації обрати: ELK чи Grafana?

Для більшості проектів Grafana Stack простіший в експлуатації та дешевший. ELK виправданий, коли потрібен складний пошук по логах (аналіз інцидентів, ретроспектива).

Алертинг

Мінімальний набір алертів (Prometheus AlertManager / Grafana Alerting):

---
- alert: APIHighErrorRate
  expr: |
    sum(rate(kong_http_requests_total{status=~"5.."}[5m])) / sum(rate(kong_http_requests_total[5m])) > 0.05
  for: 2m
  labels:
    severity: critical
  annotations:
    summary: "Error rate > 5% за останні 5 хвилин"
- alert: APIHighLatency
  expr: |
    histogram_quantile(0.95, sum(rate(kong_request_latency_ms_bucket[5m])) by (le, route) ) > 2000
  for: 5m
  labels:
    severity: warning
  annotations:
    summary: "p95 latency > 2s для роута {{ $labels.route }}"

Процес роботи та що входить у результат

1. Аналітика: вивчаємо архітектуру API, поточні шлюзи, об'єм трафіку, вимоги до зберігання. Обробляємо до 100 000 req/s.
2. Проектування: обираємо стек (Kong/AWS/Nginx), визначаємо схему логування, налаштовуємо retention на 30 днів.
3. Реалізація: розгортаємо gateway з плагінами, налаштовуємо збір метрик, підключаємо Logstash/Loki. Гарантуємо коректність конфігурації.
4. Тестування: перевіряємо коректність логів, симулюємо помилки, тестуємо алерти.
5. Деплой: публікуємо конфігурацію, навчаємо команду роботі з дашбордами.

У підсумку ви отримуєте:

• Документацію зі схеми логування та полів.
• Доступи до дашбордів (Grafana/Kibana) для кожного члена команди.
• Налаштовані алерти на критичні метрики.
• Навчання команди: як читати логи, як реагувати на алерти.
• Підтримку протягом 2 тижнів після запуску.

Строки реалізації

Базове логування та дашборди: 2–3 дні. Повноцінний стек з алертингом, трасуванням та ретроспективним аналізом: 1–2 тижні залежно від зрілості інфраструктури.

Оцінимо ваш проект і запропонуємо оптимальну конфігурацію за 1-2 дні. Зв'яжіться з нами для аудиту вашого шлюзу — ми підготуємо архітектуру та надішлемо приклад конфігурації. Отримайте консультацію з налаштування моніторингу вашого API-шлюзу прямо зараз.