Логування та моніторинг трафіку 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-шлюзу прямо зараз.

Розробка API: REST, GraphQL, WebSocket, tRPC

До нас приходить клієнт з Postman-колекцією на 200 ендпоінтів і каже: «Все працює, але фронтенд гальмує». Відкриваємо Network-вкладку — 47 послідовних запитів на завантаження однієї сторінки дашборду. Кожен чекає попереднього. Це не проблема швидкості сервера — це проблема архітектури API. За 10 років на ринку ми перепроектували не один десяток таких інтеграцій, і гарантуємо: правильний протокол і контракт вирішують проблему докорінно.

Коли REST перестає справлятися

REST добре працює для простих CRUD-операцій. Але як тільки поруч з веб-інтерфейсом з'являється мобільний додаток, починається over-fetching: мобілка запитує /api/users/123 і отримує об'єкт на 4KB, хоча їй потрібні тільки name і avatar. Помножте на список з 50 користувачів — 200KB трафіку замість 8KB.

GraphQL вирішує це через selection sets. Клієнт описує саме ті поля, які йому потрібні, і сервер повертає саме їх. На проекті з React Native + Next.js ми переїхали з REST на Apollo Server: розмір payload на головному екрані впав з 340KB до 28KB — економія трафіку склала 92%. Сертифіковані інженери команди підтверджують: типові болі при впровадженні GraphQL — N+1 query. Резолвер для поля author у поста викликає SELECT * FROM users WHERE id = ? для кожного поста у списку. На сторінці з 20 постами — 21 запит до бази. Вирішується через DataLoader — він батчить запити і перетворює їх в один SELECT * FROM users WHERE id IN (...).

Що таке tRPC і чим він кращий за REST/GraphQL?

Якщо весь стек на TypeScript (Next.js + Node/Bun), tRPC прибирає цілий шар проблем. Ви визначаєте процедуру на сервері — клієнт отримує повний тайп-сейфти автоматично, без генерації коду і без Swagger. Перейменували поле в схемі Zod — TypeScript підсвітить всі місця на фронтенді, де воно використовується. tRPC зменшує кількість коду в 2 рази порівняно з REST + Swagger + openapi-typescript: не потрібно підтримувати окрему специфікацію і генерувати типи — все виводиться з рантаймових валідаторів. Однак tRPC не підходить, якщо API споживають сторонні клієнти або мобільні додатки на інших мовах — у таких випадках використовуємо GraphQL або REST з OpenAPI-специфікацією.

WebSocket і реальний час: коли SSE, коли WS?

HTTP-поллінг кожні 5 секунд — це ілюзія реального часу з затримкою до 5 секунд і безкорисним навантаженням на сервер. Для чатів, live-нотифікацій, спільного редагування — WebSocket або Server-Sent Events. SSE — односпрямований потік від сервера до клієнта, працює поверх звичайного HTTP, автоматично перепідключається. Підходить для нотифікацій, стрімінгу даних, прогрес-барів. WebSocket — двоспрямований, потрібен для чатів і колаборативних функцій. Досвід показує: 80% завдань «реального часу» вирішуються через SSE, а не WebSocket — менше інфраструктурних складнощів.

Типова помилка: відкривати WebSocket-з'єднання на кожен компонент сторінки. На одному проекті дашборд відкривав 12 паралельних WS-з'єднань. Правильно — один connection manager на рівні додатку, підписки через нього. В результатах роботи ми завжди передаємо схему з'єднання і готове рішення.

Swagger / OpenAPI як контракт

Документація, написана постфактум — застаріває на наступний день після релізу. Ми пишемо специфікацію OpenAPI 3.1 до початку розробки, вона стає контрактом між фронтендом і бекендом. Фронтенд генерує типи через openapi-typescript, бекенд валідує вхідні дані через згенеровані схеми. Розбіжність контракту з реалізацією ловиться на CI, а не на рев'ю. Для Laravel — l5-swagger або dedoc/scramble. Для Node.js — @fastify/swagger або Zod + zod-to-openapi.

Як правильно аутентифікувати API?

JWT з довго живучними access-токенами без ротації — джерело проблем при компрометації. Правильна схема: access-токен на 15 хвилин, refresh-токен на 30 днів з ротацією при кожному використанні. Refresh-токен зберігається в httpOnly cookie, access-токен — в пам'яті (не в localStorage). Для міжсервісної взаємодії — API Keys з scope-обмеженнями або mTLS. OAuth 2.0 з PKCE для публічних клієнтів (SPA, мобілки).

Версіонування і зворотна сумісність

Ламаючі зміни в API без версіонування ламають клієнтів. Три підходи ми використовуємо в проектах:

Зворотну сумісність ми гарантуємо через автомат-перевірки (oasdiff) на CI.

Як ми розробляємо API: покроковий план

1. Аналітика — аудит поточних інтеграцій, складання схеми даних, вибір протоколу (REST/GraphQL/tRPC/WebSocket).
2. Проектування контракту — OpenAPI або SDL (GraphQL) до першого рядка коду.
3. Розробка — реалізація за контрактом, модульні тести на кожен ендпоінт.
4. Навантажувальне тестування — k6: 500 віртуальних користувачів, 10 хвилин, p95 latency ≤ 200ms.
5. Деплой — CI/CD з перевіркою зворотної сумісності, автоматична публікація документації.
6. Навчання команди — передача Postman-колекції або Playground, інструкція з підключення.

Що входить в роботу (deliverables)

• OpenAPI 3.1 специфікація (або SDL для GraphQL).
• Згенеровані клієнтські типи для TypeScript / Dart / Kotlin.
• Набір автотестів з покриттям всіх ендпоінтів (модульні + інтеграційні).
• Навантажувальні тести (k6) і звіт (p50/p95/p99 latency, RPS).
• Документація в Swagger UI / Redoc / GraphiQL.
• Навчання команди (2–4 години воркшопу).
• Підтримка протягом 30 днів після здачі (за договором).

Наш досвід

• 10+ років на ринку розробки API.
• 200+ завершених проектів (REST, GraphQL, WebSocket, tRPC).
• 50+ сертифікованих інженерів (AWS, Kubernetes, API Design).
• Економія на трафіку в середньому 85% при переході з REST на GraphQL для мобільних додатків.
• 100% зворотна сумісність — жодного зламаного клієнта за останні 3 роки.

Терміни

Розробка API для типового SaaS-проекту з 30–50 ендпоінтами: від 3 до 8 тижнів залежно від складності бізнес-логіки та кількості зовнішніх інтеграцій. Міграція існуючого REST API на GraphQL — від 2 до 6 тижнів. Додавання WebSocket-шару до готового бекенду — від 1 до 3 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.