OTel-нативний за задумом: створення продуктів, що експортують дані в будь-який стек спостережуваності

За участі Dan Gomez Blanco (New Relic).

Якщо ви створюєте self-hosted програмне забезпечення або SaaS-продукт, ваші користувачі зрештою попросять надсилати логи, трейси та метрики до їхнього власного стека спостережуваності, щоб задовольнити вимоги відповідності, керувати витратами чи централізувати всі свої дані спостережуваності в одному місці.

Привʼязування користувачів до ваших вбудованих інформаційних панелей або обмеження експорту певними вендорами створює зайві перешкоди. Натомість підтримка експорту до будь-якого бекенда, сумісного з OpenTelemetry (OTel), є незалежною від постачальників і перспективною практикою, яка дає користувачам свободу обирати свій стек спостережуваності.

У цьому дописі описано, як спроєктувати ваш продукт, щоб користувачі могли за бажанням експортувати свої логи, трейси та метрики до бекенда OTel.

Чотири сигнали спостережуваності

OpenTelemetry визначає чотири типи сигналів, які передаються стандартним протоколом OpenTelemetry (OTLP):

• Логи: записи подій, логи запитів і доступу та логи застосунків з часовими мітками й метаданими.
• Трейси: розподілені трейси та відрізки, завдяки яким користувачі бачать потоки запитів між сервісами та зіставляють їх з логами.
• Метрики: лічильники, датчики та гістограми (наприклад, частота запитів, затримка, частота помилок).
• Профілі: вибірки, які показують, де застосунки витрачають ресурси під час виконання.

Той самий підхід до експорту застосовується до всіх трьох (логів, трейсів і метрик): дайте користувачам змогу налаштувати точку доступу OTLP і надсилати до неї телеметрію. Ви можете підтримувати один, два або всі три сигнали залежно від того, що генерує ваш продукт.

Багато платформ, які підтримують експорт OTel, підтримують принаймні трейси та логи, і дедалі більше з них уже постачаються з підтримкою метрик. Проєктування одразу під усі три сигнали позбавляє від потреби додавати підтримку заднім числом.

Як виглядає «добра» система телеметрії

Надійний підхід до експорту має кілька чітких властивостей для кожного сигналу, який ви підтримуєте:

• Незалежність від постачальників: користувачі можуть вказати будь-яку сумісну з OTel точку доступу, чи то екземпляр колектора, чи один із багатьох бекендів, що підтримують OTLP напряму, без потреби створювати власні інтеграції для кожного з них.
• Без глибокої власної розробки: зовнішні платформи (або інструменти ваших користувачів) можуть інтегруватися через стандартні SDK OTel і протокол OTLP замість пропрієтарних API.
• Збереження багатого контексту: експортовані дані мають містити метадані, часові мітки та звʼязок трейсів і відрізків там, де він доступний (наприклад, записи логів, повʼязані з ідентифікаторами трейсів), щоб користувачі могли налагоджувати й аналізувати дані у своєму бекенді, не втрачаючи контексту.
• Підтримка семантичних домовленостей: дотримання семантичних домовленостей гарантує, що телеметричні дані залишаються стандартизованими та легко інтерпретуються будь-яким сумісним бекендом. Це також зменшує когнітивне навантаження на кінцевого користувача, коли він міркує про те, як працює програмна система, незалежно від того, чи це власна, чи стороння система.

Якщо ваш проєкт дотримується цих принципів для сигналів, які ви генеруєте, ви рухаєтеся в ногу з тим, як сучасні платформи підходять до експорту спостережуваності.

Два контексти: де працює ваш продукт?

Спосіб додавання експорту OTel залежить від того, кому належить система, що продукує телеметрію. Чітке розуміння цього допоможе обрати правильний підхід.

Програмне забезпечення для самостійного розгортання

Ваш продукт є застосунком або системою (наприклад, сервер ідентифікації, service mesh, база даних), яку клієнти встановлюють і запускають у своєму середовищі (власному дата-центрі, хмарі, кластері Kubernetes).

У цьому разі ви інструментуєте свій продукт за допомогою OpenTelemetry. Коли клієнт налаштовує точку доступу (наприклад, через змінні середовища або файл конфігурації), ваш застосунок експортує телеметрію з процесу, який він запускає.

Оскільки OpenTelemetry надає такі стандартні параметри конфігурації, ваші користувачі можуть очікувати того самого досвіду налаштування, який вони вже мають з будь-якою іншою системою, інструментованою через OTel.

Експорт відбувається в середовищі клієнта; він контролює і бінарний файл, і призначення. Приклади: Keycloak, Kuma.

Хмарні платформи

Ваш продукт є платформою, де клієнти розгортають власні застосунки або користуються вашими керованими сервісами (наприклад, PaaS, serverless, API-шлюз). Робоче навантаження виконується на вашій інфраструктурі.

У цьому разі ви додаєте функцію платформи, як-от “Telemetry Drains” або “Observability Destinations”, яка дає клієнтам змогу налаштувати, куди надсилати телеметрію. Ваша платформа збирає телеметрію з їхнього робочого навантаження (а також з ваших власних сервісів, як-от роутерів) і пересилає її до точки доступу OTLP клієнта.

Експорт виконує ваша інфраструктура, а не бінарний файл застосунку, який запускає клієнт. Приклади: Heroku, Cloudflare.

Стисло: програмне забезпечення, яке розгортає користувач → зосередьтеся на вбудованому інструментуванні та налаштуванні точки доступу. Платформа, яку експлуатуєте ви → зосередьтеся на налаштовуваних призначеннях експорту, які ваша інфраструктура використовує для пересилання даних.

Як це роблять інші

У цьому дописі розглянуто чотири інтеграції (Kuma, Keycloak, Cloudflare і Heroku) як показові приклади в обох контекстах вище, але вони аж ніяк не єдині, хто вже експортує телеметрію нативно через OTLP. На сторінці Інтеграції OpenTelemetry зібрано бібліотеки та сервіси, які надають нативне інструментування або готові плагіни.

Нижче показано, як ці чотири інтеграції працюють з усіма трьома сигналами (або їх підмножиною) і чого з них можна навчитися.

Підхід для самостійного розгортання: Kuma і Keycloak

Якщо ваші користувачі розгортають ваше програмне забезпечення у власних середовищах, найкраща практика полягає в тому, щоб постачати застосунок уже інструментованим через OpenTelemetry і надавати прапорці конфігурації для їхніх точок доступу OTLP.

Kuma

Чи запускають клієнти панелі управління та даних Kuma у власних кластерах Kubernetes, чи на віртуальних машинах, вона постачається попередньо налаштованою для генерації логів, трейсів і метрик у бекенд OTel.

Користувачі налаштовують експорт, який виконується з їхніх розгортань Kuma, через політики mesh:

• MeshAccessLog: спрямовує логи доступу до колектора OTel (точка доступу + атрибути, як-от назва mesh і час початку).
• MeshTrace: обробляє розподілені трейси з налаштовуваною вибіркою та тегуванням.
• MeshMetric: надає метрики панелі управління та даних. Інтегрується з OpenTelemetry та Prometheus.

Наприклад, надсилання трейсів до бекенда OTel виглядає так:

# MeshTrace policy
backends:
  - type: OpenTelemetry
    openTelemetry:
      endpoint: otel-collector:4317

Надсилання логів доступу відбувається за точно таким самим шаблоном, але з іншою політикою:

# MeshAccessLog policy
backends:
  - type: OpenTelemetry
    openTelemetry:
      endpoint: otel-collector:4317
body:
  kvlistValue:
    values:
      - key: mesh
        value:
          stringValue: '%KUMA_MESH%'
attributes:
  - key: start_time
    value:
      stringValue: '%START_TIME%'

Додаткове читання:

• Kuma MeshAccessLog – OpenTelemetry
• Kuma MeshTrace (бекенд OpenTelemetry)
• Спостережуваність Kuma

Keycloak

Keycloak є ще одним прикладом self-hosted програмного забезпечення, яке надає чудову функціональність експорту телеметрії.

Замість окремого sidecar-контейнера чи функції платформи користувачі просто передають прапорець запуску, що вказує на точку доступу їхнього колектора, і сам процес Keycloak виконує експорт.

Він використовує єдину точку доступу телеметрії, але надає детальні прапорці для перемикання окремих сигналів:

• Трейси: tracing-enabled=true (охоплює HTTP-запити, DB, LDAP, вихідні HTTP/IdP).
• Метрики: детальні метрики, що надаються через ту саму інтеграцію OTel.
• Логи: наразі в режимі попереднього перегляду та вимкнені стандартно (--features=opentelemetry-logs --telemetry-logs-enabled=true, а --telemetry-logs-level задає фільтрацію за рівнем).

Визначення точки доступу, додаткових заголовків і бажаного протоколу (gRPC або HTTP) виглядає так:

bin/kc.sh start --telemetry-endpoint=http://my-otel-endpoint:4317 --telemetry-protocol=grpc

Додаткове читання:

• Keycloak Observability / Telemetry

Підхід на рівні платформи: Cloudflare і Heroku

Коли ви контролюєте інфраструктуру, найпростіший досвід для користувача полягає в тому, щоб виконувати експорт на рівні платформи, витягуючи дані з робочого навантаження користувача та надсилаючи їх до його призначення.

Cloudflare Workers

Оскільки користувачі запускають свій код безпосередньо на інфраструктурі Cloudflare, вона виконує експорт через функцію платформи Observability Destinations. Вона пропонує користувачам зручний підхід: вони можуть налаштувати точку доступу OTLP у своїй панелі. Після цього Cloudflare автоматично надсилає трейси та логи з Workers до цього призначення.

Хоча метрики поки не підтримуються, дані трейсів забезпечують глибоку наскрізну видимість, фіксуючи виклики обробників, привʼязки, вихідні fetch-виклики тощо. Користувачі також можуть налаштувати частоту вибірки у своєму wrangler.toml.

Додаткове читання:

• Експорт даних OpenTelemetry з Workers
• Cloudflare Workers і трейси

Heroku

Heroku застосовує дещо інший, дуже гнучкий підхід із Telemetry Drains. Користувачі додають призначення, вказуючи точку доступу, протокол транспорту та заголовки, а потім явно обирають, які сигнали експортувати.

Потім платформа Heroku збирає дані як із застосунку користувача (через SDK OTel), так і з власних сервісів (як-от їхній Router) і надсилає їх до призначення.

heroku telemetry:add <endpoint> --app <app-name> --signals traces,metrics,logs --transport http --headers '{"Authorization": "ingestion key"}'

Надання користувачам детального контролю над тим, які сигнали експортувати, є прагматичним шаблоном проєктування, особливо для команд, які прагнуть керувати обсягом даних і витратами на приймання.

Додаткове читання:

• Телеметрія Heroku
• Сигнали та атрибути OpenTelemetry у Heroku
• Робота з Heroku Telemetry Drains

Проєктування вашої моделі експорту

Для всіх трьох основних сигналів телеметрії фундаментальне архітектурне питання залишається незмінним: ваша платформа вимагатиме від користувача опитувати API для отримання даних через регулярні інтервали, чи доставлятиме телеметрію безпосередньо до визначеної користувачем точки доступу?

Класичний підхід: власні API для опитування

Традиційно платформи надавали телеметрію через API, які користувачі мали опитувати через регулярні інтервали, обробляти посторінкову навігацію та приймати результати у свої бекенди.

Це розумна відправна точка, якщо у вас уже є зріле, добре перевірене API для логів чи метрик, адже розширити його часто простіше, ніж будувати новий шлях надсилання. Однак це має реальні витрати:

• Ви перекладаєте значну операційну відповідальність на своїх користувачів. Тепер вони мають створювати масштабовані системи опитування, здатні керувати інтервалами опитування, обробляти посторінкову навігацію відповідей API, повторювати спроби після збоїв і заповнювати пропущені дані.
• Користувачі можуть створювати власні рішення, які не масштабуються, не дотримуються ваших стандартів і вимагають значних витрат на підтримку з їхнього боку в міру розвитку схеми вашого API разом із платформою.
• Досягти майже реального часу доставки стає значно складніше, а це часто критична вимога для чутливих до затримок сигналів, як-от трейси та метрики.

Для логів реалізація на основі витягування часто виглядає так (наприклад, у стилі CloudWatch Logs):

state: last_end_time
every poll_interval:
  start_time = last_end_time
  end_time   = now()
  next_token = null
  do:
    response = FilterLogEvents(log_groups, start_time, end_time, next_token)
    emit(response.events)
    next_token = response.nextToken
  while next_token != null

Тут вам знадобилася б схожа логіка відстеження стану для API метрик або трейсів.

Попри те, що користувачам доводиться писати власний код для перетворення відповідей вашого API у стандартні формати, модель власного опитування працездатна для кожного підтримуваного сигналу, коли ви не можете вдатися до стандартизованішого підходу, як-от Prometheus.

Однак для нових проєктів вона не повинна бути типовим вибором.

Підхід, орієнтований на стандарти: OTLP

Для орієнтованої на розробників телеметрії в реальному часі надсилання через OTLP стало домінантним шаблоном.

Замість очікування запиту ваш сервіс (або OpenTelemetry Collector, який ви запускаєте) активно експортує логи, трейси та метрики безпосередньо до налаштованої користувачем точки доступу через OTLP (поверх HTTP або gRPC).

Він використовує один незалежний від постачальників галузевий стандартний протокол для всієї телеметрії, тож вам не доведеться повторно реалізовувати логіку доставки телеметрії для кожного окремого сигналу, який ви підтримуєте.

Крім того, OTLP надає повноцінну підтримку структурованих даних і метаданих, що допомагає автоматично зберігати важливий контекст, як-от звʼязок конкретних записів логів з ідентифікаторами їхніх батьківських трейсів.

З погляду користувача це практично працює «з коробки». Будь-який сумісний з OTel бекенд може приймати дані майже в реальному часі без потреби у власній логіці опитування.

Побудова досвіду експорту

Реалізуючи модель експорту у своєму продукті, прагніть максимальної гнучкості за мінімальної конфігурації.

Дайте користувачам змогу налаштувати точку доступу OTLP

Почніть із того, щоб користувачі могли вказати власну точку доступу OTLP і потрібні заголовки автентифікації (як-от ключ приймання).

Але не зупиняйтеся на цьому!

Щоб користувачі могли контролювати обсяг експорту, спростити керування даними та зменшити витрати, дайте їм змогу явно перемикати, які сигнали вони хочуть експортувати, за прикладом Heroku.

Стандартизуйте архітектуру

Під капотом у вас є два основні варіанти: використовувати SDK OpenTelemetry безпосередньо у своїх сервісах для генерації даних або запускати внутрішній колектор OTel, який збирає телеметрію вашої системи та повторно експортує її до точки доступу користувача.

Дотримання стандартних змінних середовища OpenTelemetry (як-от OTEL_EXPORTER_OTLP_ENDPOINT) робить базову інфраструктуру надійною, а також зручною для документування та осмислення.

Підтримуйте узгоджену семантику

Окрім змінних середовища на основі OTel, подбайте про узгоджену семантику в усіх своїх сигналах. Семантичні домовленості є вашим довідником для узгодженого найменування атрибутів і схем, а також для розуміння того, як саме логи та метрики повʼязані з ідентифікаторами трейсів і відрізків. Weaver, який будується на семантичних домовленостях, дає змогу визначати власні назви атрибутів і схеми, тримати їх у синхроні з еволюцією коду й інфраструктури та підтримувати федеративні реєстри семантичних домовленостей.

Коли користувач приймає вашу телеметрію у свій бекенд спостережуваності, усе має зʼєднуватися наскрізно, щоб скласти повну картину.

Одна з переваг цього підходу полягає в тому, що ви позбавляєтеся потреби створювати різні інтеграції з вендорами. Експортуючи телеметрію через OTLP, ви даєте користувачам змогу перетворювати та приймати її у потрібних їм форматах.

Наприклад, користувач може захотіти пересилати логи до свого бекенда та до обʼєктного сховища на кшталт S3, щоб дотримати вимоги відповідності.

Маршрутизація телеметрії до користувача

Проєктуючи інтерфейс конфігурації для своїх користувачів, вам потрібно вирішити, наскільки детальною має бути маршрутизація телеметрії. Зазвичай є два шляхи, кожен з яких розрахований на свій тип користувача.

Єдина точка доступу

Для переважної більшості користувачів ідеальною є конфігурація з єдиною точкою доступу. Тут користувач вводить одну базову URL-адресу, а ваш експортер внутрішньо додає стандартні шляхи OTLP (v1/traces, v1/metrics і v1/logs).

Точки доступу для окремих сигналів

Великі клієнти або ті, хто керує складними конфігураціями спостережуваності, можуть захотіти надсилати сигнали телеметрії до різних платформ.

OTLP нативно підтримує це за допомогою змінних для конкретних сигналів за шаблоном OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT разом із відповідними конфігураціями заголовків. Наприклад, щоб налаштувати окрему точку доступу для логів, скористайтеся OTEL_EXPORTER_OTLP_LOGS_ENDPOINT.

Надання такої маршрутизації за сигналами у вашому застосунку технічно необовʼязкове, але це суттєва перевага для досвідчених користувачів.

Запуск колекторів для керування мультиорендністю

Коли ви вже надсилаєте через OTLP (для будь-якої комбінації логів, трейсів і метрик), вам усе одно потрібно вирішити, як запускати колектори для керування кількома орендарями.

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

Один колектор на орендаря

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

Це забезпечує надійні гарантії логічної ізоляції. Уповільнення чи помилки конфігурації в конвеєрі одного клієнта не впливають на інших.

Хоча ви можете зібрати власний бінарний файл колектора, який містить лише необхідні компоненти, розгортання сотень чи тисяч екземплярів колектора стане ресурсомістким.

Через цей компроміс така архітектура зазвичай найкраще підходить для корпоративних SaaS-продуктів, де надійна мультиорендна ізоляція є суворою вимогою, а клієнти можуть мати складні конфігурації точок доступу.

Спільний колектор зі статичними конвеєрами на орендаря

Тут “статичний” означає, що конвеєр і правила маршрутизації кожного орендаря визначені заздалегідь у файлі конфігурації колектора, а не створюються динамічно під час виконання.

За духом це близько до патерну розгортання шлюзу: уся телеметрія вашої платформи стікається в один централізований колектор. Усередині ви визначаєте окремі конвеєри для кожного орендаря. Конектор маршрутизації тут підходить ідеально: він спрямовує дані до потрібного конвеєра (а отже, до потрібної зовнішньої точки доступу) на основі атрибутів ресурсу, як-от ідентифікатор орендаря.

Цей шаблон добре працює для команд на ранньому або середньому етапі масштабування, де експлуатувати одне розгортання простіше, ніж керувати окремими екземплярами для кожного орендаря. Вам потрібно моніторити та масштабувати лише одне розгортання, а вся маршрутизація налаштована в одному місці.

Однак вам доведеться бути готовими керувати динамічним файлом конфігурації, що зростає разом із клієнтською базою.

Власні API для опитування проти OTLP: вердикт

Коли постає вибір між тим, щоб змушувати користувачів опитувати власні API, і тим, щоб дозволити їм приймати дані через спільний стандарт, більшість сучасних платформ, орієнтованих на розробників, мають обрати друге. Вдавайтеся до власних API для опитування, лише якщо стандартизація неможлива.

Уніфікований протокол OpenTelemetry зберігає багатий контекст, доставляє дані майже в реальному часі та довів свою здатність працювати в масштабі як у хмарних, так і в self-hosted розгортаннях Cloudflare, Heroku, Kuma та Keycloak. До того ж незалежність OpenTelemetry від конкретного вендора дає користувачам свободу перемикатися між бекендами спостережуваності відповідно до бізнес-потреб, без повної перебудови своїх конвеєрів телеметрії.

Однак впровадження OpenTelemetry не дається безкоштовно, адже вашій команді доведеться витратити час на вивчення й реалізацію OpenTelemetry та створити потрібну документацію, щоб скерувати користувачів і внутрішні команди щодо найкращих практик.

Через зростання впровадження OTel у сфері спостережуваності (нещодавно проєкт отримав статус дипломованого в CNCF) ця початкова інвестиція окупиться, коли ви інтегруватимете у свою платформу інструменти, які покладаються на OpenTelemetry для експорту власної телеметрії.

Збираємо все докупи

Підсумовуючи: вам не потрібно створювати спеціальні інтеграції, щоб дозволити користувачам експортувати телеметрію до їхніх власних бекендів.

Якщо ви готові впровадити нативний для OTel експорт у своєму застосунку, ось стислий перелік ключових архітектурних кроків і кроків проєктування:

• Визначте, які сигнали телеметрії підтримувати з-поміж логів, трейсів і метрик. В ідеалі варто підтримувати всі три, але почніть з того, що генерує ваш продукт.
• Використовуйте OTLP для експорту цих сигналів через SDK OTel або колектор. Та сама архітектура на основі надсилання (push) працює для всіх трьох сигналів.
• Дайте користувачам змогу налаштувати точку доступу призначення та додаткові заголовки автентифікації. Розгляньте точки доступу для окремих сигналів для команд зі складнішими конфігураціями.
• Дозвольте користувачам вмикати чи вимикати окремі сигнали, щоб контролювати обсяг даних і витрати.
• Задокументуйте формат точки доступу (gRPC/HTTP), потрібні заголовки та семантику атрибутів і схем для кожного сигналу, щоб користувачі могли впевнено покладатися на дані у своїх бекендах.
• Оберіть топологію колекторів: один колектор на орендаря для надійної ізоляції або спільний колектор з конвеєрами на орендаря для менших операційних витрат.
• Надайте приклад конфігурації або фрагмент зі змінними середовища, щоб користувачі могли швидко почати.

Наведені вище пункти також втілюють золоті правила, яких дотримуються Cloudflare (крім метрик), Heroku, Kuma та Keycloak: стандартно надсилати (push), залишатися незалежними від постачальників і документувати контракт.

Проєктування одразу під усі три сигнали з використанням відкритих стандартів усуває зайві перешкоди, зменшує інженерні накладні витрати та дає клієнтам змогу найкраще використовувати свої дані на власних умовах.

• ←Попередня
• Наступна→