Налаштування GraphQL моніторингу (Apollo Studio / GraphQL Hive)

Після переходу з REST на GraphQL команди часто втрачають контроль над продуктивністю. Типова картина: запит гальмує, але незрозуміло, який резолвер винен. N+1 запити маскуються під нормальні відповіді, а несумісна зміна схеми ламає мобільний додаток. Ми впровадили моніторинг GraphQL для 50+ проєктів — від стартапів до enterprise — і знаємо, які інструменти реально працюють у production. В одному випадку p95 latency операцій зросла з 200 до 800 мс за тиждень. Тільки трасування резолверів показало, що проблема в новому обробнику user.orders, який робив 50 окремих запитів до бази. Моніторинг допоміг виявити це за годину, скоротивши час діагностики з годин до хвилин, і після усунення N+1 latency впала на 60%.

Проблеми, які вирішуємо

• Невидимість польового використання: Apollo Studio показує, які поля реально запитують клієнти. Це допомагає видалити deprecated поля без страху.
• Повільні резолвери без трасування: OpenTelemetry з Jaeger/Tempo дозволяє побачити, який саме обробник гальмує — до рівня аргументів.
• Breaking changes схеми: автоматична перевірка зворотної сумісності при кожному деплої запобігає падінню production.

Як ми це робимо: стек і конфіги

Apollo Studio (GraphOS)

// Установка
npm install @apollo/server @apollo/server/plugin/usageReporting

import { ApolloServer } from '@apollo/server'
import { ApolloServerPluginUsageReporting } from '@apollo/server/plugin/usageReporting'

const server = new ApolloServer({
  typeDefs,
  resolvers,
  plugins: [
    ApolloServerPluginUsageReporting({
      // APOLLO_KEY зі змінних середовища
      sendVariableValues: {
        // Не відправляти чутливі змінні
        exceptNames: ['password', 'token', 'secret']
      },
      sendHeaders: {
        exceptNames: ['Authorization', 'Cookie']
      },
      // Вибірка трасувань (100% дорого, 10% достатньо для аналізу)
      fieldLevelInstrumentation: 0.1
    })
  ]
})

Згідно з документацією Apollo Studio, платформа надає: розбивку p50/p95/p99 latency по операціях, field usage, schema checks з реальними клієнтськими запитами, алерти по деградації.

GraphQL Hive (self-hosted альтернатива)

# Docker Compose для GraphQL Hive
docker run -d \
  -e HIVE_TOKEN=your-token \
  -e TARGET=your-org/your-project/production \
  ghcr.io/kamilkisiela/graphql-hive/cli:latest

import { useHive } from '@graphql-hive/client'
import { envelop, useSchema } from '@envelop/core'

const getEnveloped = envelop({
  plugins: [
    useSchema(schema),
    useHive({
      enabled: true,
      token: process.env.HIVE_TOKEN,
      usage: {
        sampleRate: 1.0,
        exclude: ['IntrospectionQuery']
      },
      reporting: {
        author: 'CI Pipeline',
        commit: process.env.GIT_SHA
      }
    })
  ]
})

OpenTelemetry трасування резолверів

Для self-hosted моніторингу з Jaeger/Tempo використовуємо плагін, який створює span на кожен обробник. Це дозволяє бачити повну картину запиту, включаючи виклики до баз даних. OpenTelemetry — безкоштовний open-source, витрати лише на хостинг колектора (~$30-50/міс).

Порівняння Apollo Studio vs GraphQL Hive

Apollo Studio зручніший для швидкого старту, але GraphQL Hive може бути економічнішим при великих обсягах (до 40% економії за рахунок self-hosted).

Типові метрики моніторингу

Як вибрати між Apollo Studio та GraphQL Hive?

Якщо потрібне швидке хмарне рішення без адміністрування — Apollo Studio. Якщо вимоги до data residency або бюджет великий — обирайте Hive. Ми допомагаємо з вибором на етапі аудиту.

Чому варто додати OpenTelemetry додатково?

OpenTelemetry дає повне трасування запиту, включаючи виклики до сторонніх API та баз даних. Apollo Studio/Hive бачать лише GraphQL-шар. Поєднання дає 100% видимість. Це також дозволяє виявити вплив на Core Web Vitals за рахунок оптимізації TTFB.

Типові помилки при налаштуванні

• Занадто низький sample rate (менше 1%) — статистично недостовірні p99.
• Відсутність фільтрації чутливих даних — витік credentials через метрики.
• Ігнорування schema change alerts при деплої — ризик breaking changes.

Процес роботи з налаштування

1. Аналітика: аудит поточної схеми, виявлення вузьких місць за допомогою @apollo/rover або graphql-inspector.
2. Проєктування: вибір інструменту (Apollo Studio, Hive або OpenTelemetry), проєктування метрик (p50/p95/p99, error rate, Prometheus метрики).
3. Реалізація: інтеграція плагіна, налаштування трасування резолверів, публікація схеми.
4. Тестування: перевірка на staging, порівняння показників до/після. В одному проєкті знизили p95 latency з 2с до 300 мс.
5. Деплой і алерти: налаштування сповіщень у Slack/Telegram при деградації (наприклад, p95 latency > 500ms), а також Grafana дашборди.

Що входить і терміни

Налаштування GraphQL моніторингу займає від 2 до 5 робочих днів залежно від складності схеми та обраного рішення. Включає: підключення Apollo Studio або GraphQL Hive з публікацією схеми, трасування резолверів через OpenTelemetry (Jaeger/Tempo), Prometheus метрики + Grafana дашборд з панелями «Top Slow Operations», «Error Rate», «Slowest Resolvers», налаштування алертів та автоматичних перевірок зворотної сумісності, документацію з експлуатації.

Інвестиції в моніторинг окупаються в середньому за 2-3 місяці — скорочення часу на пошук проблем і запобігання інцидентам економить бюджети. Звертайтеся до нас для налаштування моніторингу під ваш проєкт. Отримайте консультацію щодо вибору інструментів та швидкої інтеграції.

Розробка 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 тижнів. Вартість розраховується індивідуально після аудиту. Отримайте консультацію — зв'яжіться з нами, щоб обговорити ваш проект.