Ми стикалися з проектами, де прод починає сипати 500-ми через перевантаження одного ендпоінта, а розробники витрачають години на пошук причини за розрізненими логами. Без єдиної точки входу — шлюзу — ви сліпі: не бачите, хто викликає API, з якою затримкою, які роути падають. Налаштування логування та моніторингу трафіку через API Gateway вирішує ці проблеми за кілька днів і дає прозорість усього трафіку. Наш досвід впровадження подібних рішень гарантує стабільність і скорочення часу пошуку інцидентів до 15 хвилин.
Ми інтегруємо у ваш шлюз збір мінімально необхідних полів: request_id (наскрізна трасування), consumer_id (ідентифікація клієнта), method, path, status_code, latency_ms, розміри запитів. Тіло запиту не логуємо за замовчуванням — тільки в дебаг-режимі для вибраних роутів, щоб не світити чутливі дані. Після впровадження одна з команд скоротила час пошуку інцидентів з 2 годин до 15 хвилин.
Які метрики критичні для налагодження API?
Без централізованого збору ви не зможете швидко відповісти на питання: який ендпоінт найповільніший, хто генерує 90% помилок, чому впав upstream. Ми налаштовуємо шлюз так, щоб кожен запит залишав повний цифровий слід:
| Поле | Приклад | Навіщо |
|---|---|---|
request_id |
uuid4 |
Наскрізна трасування через сервіси |
consumer_id |
client_abc |
Хто робить запит |
method + path |
GET /api/v2/orders |
Статистика за ендпоінтами |
status_code |
429 |
Моніторинг помилок |
latency_ms |
143 |
Продуктивність |
upstream_latency_ms |
138 |
Де витрачається час |
request_size |
1024 |
Аномалії в трафіку |
response_size |
4096 |
— |
ip |
1.2.3.4 |
Безпека |
Кожен запит також збагачується мітками (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?
| Критерій | ELK (Elasticsearch, Logstash, Kibana) | Grafana Stack (Loki, Prometheus, Grafana) |
|---|---|---|
| Зберігання логів | Індексує всі поля — дорого | Зберігає стиснуті логи без індексації — дешево |
| Пошук по логах | Повнотекстовий, швидкий | Обмежений (за мітками) |
| Метрики | Тільки через beats | Prometheus — нативний |
| Складність налаштування | Висока (Logstash pipeline) | Середня (PromQL, LogQL) |
| Типова ціна для 100 ГБ/день | 200–400 $/міс | 50–100 $/міс |
Для більшості проектів 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 }}" Типові помилки при налаштуванні логування
- Забувають увімкнути `request_id` — втрачається наскрізна трасування. - Вмикають `dataTraceEnabled` у production — витік даних і зростання вартості зберігання. - Не налаштовують ротацію логів — переповнення диска. - Не тестують алерти на staging — хибні спрацьовування в prod.Процес роботи та що входить у результат
- Аналітика: вивчаємо архітектуру API, поточні шлюзи, об'єм трафіку, вимоги до зберігання. Обробляємо до 100 000 req/s.
- Проектування: обираємо стек (Kong/AWS/Nginx), визначаємо схему логування, налаштовуємо retention на 30 днів.
- Реалізація: розгортаємо gateway з плагінами, налаштовуємо збір метрик, підключаємо Logstash/Loki. Гарантуємо коректність конфігурації.
- Тестування: перевіряємо коректність логів, симулюємо помилки, тестуємо алерти.
- Деплой: публікуємо конфігурацію, навчаємо команду роботі з дашбордами.
У підсумку ви отримуєте:
- Документацію зі схеми логування та полів.
- Доступи до дашбордів (Grafana/Kibana) для кожного члена команди.
- Налаштовані алерти на критичні метрики.
- Навчання команди: як читати логи, як реагувати на алерти.
- Підтримку протягом 2 тижнів після запуску.
Строки реалізації
Базове логування та дашборди: 2–3 дні. Повноцінний стек з алертингом, трасуванням та ретроспективним аналізом: 1–2 тижні залежно від зрілості інфраструктури.
Оцінимо ваш проект і запропонуємо оптимальну конфігурацію за 1-2 дні. Зв'яжіться з нами для аудиту вашого шлюзу — ми підготуємо архітектуру та надішлемо приклад конфігурації. Отримайте консультацію з налаштування моніторингу вашого API-шлюзу прямо зараз.