OpenTelemetry Vocabulary: Tracing, Metrics, and Logs Explained (англійською)

OpenTelemetry (часто скорочується до OTel) став промисловим стандартом для інструментування розподілених систем. Якщо ваша команда переходить від SDK певного виробника до OTel, пише Runbooks для спостережливості або переглядає PR інструментів, вам потрібен точний словник. Зрозуміння цих термінів також допомагає вам чітко спілкуватися з SRE і командами платформи.

---

Типи сигналів

** Traces ** — записи від початку до кінця окремого запиту, який поширюється через розподілену систему. Трасс складається з spans. Відповідь слідів: “Куди пішов цей запит і скільки часу зайняв кожен крок?”

** Метрика ** — Числові виміри, агреговані за часом. OTel підтримує чотири типи метричних приладів: * Counter * (монотонно зростаюче), * Gauge * (значення в точці часу), * Gistogram * (розподіл значень) і * UpDownCounter * (може зростати або зменшуватися).

** Журнали ** — записи дискретних подій з часом. Журнали OTel стандартизуються для інтеграції з слідами і метриками за допомогою спільного контексту. Фраза: * “Цель OTel - це об’єднаний сигнал: журнали, метрики і сліди, всі пов’язані з ідентифікатором сліду.” *

---

Шляхи і шляхи

** Обсяг ** — окрема одиниця роботи у межах трасування: запит бази даних, виклик HTTP, виконання функції. Кожен діапазон має назву, час початку, тривалість, стан і додатковий атрибут. Фраза: “Спектр запиту бази даних показує 450 мс — це затримка.”

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

** ІД діапазону ** — унікальний ідентифікатор для окремого діапазону у трасі.

** Батьківський діапазон ** — діапазон, який спричинив створення поточного діапазону. Кожен діапазон, крім кореня, має батька.

** Корінь розширення ** — Перше розширення у трасі, яке зазвичай створюється у точці вводу запиту (наприклад, обробник HTTP у службі інтерфейсу).

** Контекстне розповсюдження ** — Механізм, за допомогою якого контекст трасування (ІД трасування, ІД діапазону, рішення про вибірку) передається між службами, зазвичай за допомогою заголовків HTTP (наприклад, traceparent і tracestate зі специфікації W3C Trace Context). Фраза: “Без контекстного розповсюдження, кожна служба створює ізольований слід — ви не можете їх корелювати.”

** Багаж ** — пари ключ- значення, приєднані до контексту трасування і розповсюджені за межами служб. Корисно для передачі метаданих рівня запиту (наприклад, ідентифікатора користувача, регіону) без зміни підписів функцій. Фраза: “Ми передаємо ідентифікатор орендаря як OTel багаж, тому служби нижнього рівня можуть мітки їхні проміжки без читання JWT знову.”

---

Експорт і імпорт

** Бібліотека інструментів ** — Бібліотека, яка автоматично додає інструменти OTel до фрейму або компонента сторонньої програми (наприклад, автоматичне інструментування для Express, Django, JDBC). Фраза: “Biblioteka przyrządów OTel dla Express automatycznie tworzy zakresy dla każdego wchodzącego zapytania HTTP.”

** Авто- інструментування ** — інструментування служби без зміни коду програми, за допомогою агента OTel або SDK, який прив’ язується до внутрішніх компонентів фрейму. Фраза: “Ми використовуємо Java auto-instrumentation через агент OTel — не потрібні зміни коду.”

** Ручне інструментування ** — додавання викликів API OTel безпосередньо у код програми для створення нетипових діапазонів або додавання атрибутів до існуючих діапазонів. Фраза: “Ми додали ручні інструменти навколо логіки обробки платежу, щоб захопити час відповіді постачальника платежу як атрибут спектру.”

** Exporter ** — компонент OTel, який надсилає дані телеметрики до сервера (Jaeger, Prometheus, Tempo, платформа виробника). Кожен тип сигналу має свій власний експорт.

** OTLP (OpenTelemetry Protocol) ** — стандартний дротяний протокол для надсилання даних OTel до збирача або сервера. OTLP через gRPC або HTTP є рекомендованим підходом. Фраза: “Ми експортуємо сліди через OTLP до OTel Collector, який роздає їх Jaeger і нашому SIEM.”

** OTel Collector ** — проксі- сервер, незалежний від виробника, який отримує, обробляє і експортує телеметричні дані. Він може фільтрувати, відбирати і перетворювати дані перед їх пересиланням. Фраза: “Маршрутизація всього OTLP-трафіку через Collector — це дозволяє нам змінювати backends без зміни конфігурації програми.”

** Ресурс ** — метадані, що описують джерело телеметричних даних: назва служби, версія, середовище, вузол, назва поду Kubernetes. Ресурси приєднуються до всіх сигналів, що надходять від служби. Фраза: “Встановіть атрибут ресурсу service.name правильно — так сліди групуються в інтерфейсі користувача.”

** Вибірка ** — вибір слідів для запису і експорту. * Вибірка за головним елементом * визначає сліди на кореневому рівні; * вибірка за хвостовим елементом * визначає сліди після перегляду повного сліду. Фраза: “Ми використовуємо 10% швидкість вибірки на основі голови в виробництві - вибірка на основі хвоста є на дорозі, як тільки ми оновимо збірник.”

---

Як інженери говорять про OTel в PRs

• • “Додати діапазон навколо зовнішнього виклику HTTP, щоб ми могли побачити його затримку окремо.” *
• • “Тракт показує, що вузької місця є в службі збагачення, а не в базі даних.” *
• “Не вдалося продовжити контекстне поширення — дочірня служба створює новий кореневий обсяг замість продовження трасування.”
• • “Встановити стан діапазону на ERROR і записати виняток як подію діапазону.” *

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

На практиці: Навігація розмов навколо спостережливості

Будьмо чесними - іноді термінологія навколо спостережливості відчувається… щільною. При роботі з командами, де всі не володіють технічним жаргоном, або при спілкуванні в різних культурах, це може легко призвести до непорозумінь. Фраза, яка здається вам абсолютно зрозумілою, може звучати абсолютно заплутано для когось іншого, особливо якщо вони все ще розвивають свої професійні навички англійської мови. Це не просто про те, щоб знати * визначення * “слідкування”, “метрики” і “журналів”; це про те, як ви сформулюєте ці поняття, і як чітко ви можете попросити про пояснення, коли це потрібно.

Наприклад, уявіть, що ви переглядаєте запит на витяг (Pull Request, PR), який використовує OpenTelemetry. Коментар від одного з ваших колег може бути таким: « Чи можемо ми додати більше вибірки до цього сліду? Обсяг досить великий.” Хоча це технічно коректно - пропонуючи зменшити кількість зібраних слідів - це не відразу передає * чому * це важливо. Не рідною англійською мовою, незнайомий з концепцією «сліду обсягу» і його наслідків для продуктивності системи, може просто запитати: «Що означає «вибірка» тут? І чому це проблема?» — важливо перетворити технічну рекомендацію на щось більш доступне — можливо: «Зменшення вибірки допоможе нам зосередитися на найкритичніших шляхах в цьому сліді, що дасть нам кращі знання про потенційні вузли і зменшить навантаження на нашу інфраструктуру слідування»

Інший сценарій може включати обговорення Slack про додавання метрики до нової служби. Хтось може сказати: « Давайте покажемо всі часи запиту бази даних як метрику ». Це припускає, що всі розуміють, що означає « показ » у цьому контексті — зробити ці дані доступними для моніторингу. Колега з Іспанії, можливо, новий для команди, може відповісти: “Але чи не повинні ми відстежувати тільки важливі запити? Чи є якісь конкретні показники, яким ми повинні надавати пріоритет?» Це підкреслює необхідність у роз’ ясненні, які показники є справді цінними і як вони пов’ язані з загальним станом системи. Це про те, щоб вийти за рамки простого збору даних і зосередитися на тому, що ці дані насправді значать.

Нарешті, розгляньте опис PR: « Реалізувати поширення контексту OpenTelemetry у всіх мікросервісах ». Розробник, який не знайомий з нюансами поширення контексту, може не знати, чому це потрібно. Пояснення цього як «забезпечення того, що інформація про запит подорожує з службою, коли вона переміщається між різними компонентами» - використовуючи простішу мову - може значно поліпшити розуміння і співпрацю.

# Example OpenTelemetry Python SDK trace creation
import opentelemetry.trace as trace

tracer = trace.get_tracer(__name__)

span = tracer.start_span("my-service-function")
try:
    result = 10 / 2
    print(f"Result: {result}")
finally:
    span.end()

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