Екосистема інструментування

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

• Категорії інструментування, що охоплюють різні випадки використання та шаблони встановлення.
• Поширення контексту забезпечує кореляцію між трейсами, метриками та журналами, дозволяючи сигналам доповнювати один одного.
• Семантичні домовленості визначають, як створювати телеметрію для стандартних операцій.
• Інструментування журналів, яке використовується для отримання журналів з наявної системи логів Java в OpenTelemetry.

Категорії інструментування

Є кілька категорій інструментування:

• Без програмування: Java-агент є формою інструментування без програмування [1], яке динамічно маніпулює байт-кодом застосунку.
• Без програмування: Spring Boot стартер є формою інструментування без програмування [1], яке використовує spring autoconfigure для встановлення бібліотечного інструментування.
• Бібліотечне інструментування обгортає або використовує точки розширення для інструментування бібліотеки, вимагаючи від користувачів встановлення та/або адаптації використання бібліотеки.
• Нативне інструментування вбудоване безпосередньо в бібліотеки та фреймворки.
• Ручне інструментування написане авторами застосунків і зазвичай специфічне для сфери використання застосунку.
• Шими переносять дані з однієї бібліотеки спостережуваності в іншу, зазвичай з якоїсь бібліотеки в OpenTelemetry.

[1]: Інструментування без програмування встановлюється автоматично на основі виявлених бібліотек / фреймворків.

Проєкт opentelemetry-java-instrumentation містить вихідний код для Java-агента, Spring Boot стартера та Бібліотечного інструментування.

Без програмування: Java-агент

Java-агент є формою автоматичного інструментування без програмування яке динамічно маніпулює байт-кодом застосунку.

Для списку бібліотек, інструментованих Java-агентом, дивіться колонку “Автоматично інструментовані версії” у підтримуваних бібліотеках.

Дивіться Java-агент для отримання додаткової інформації.

Без програмування: Spring Boot стартер

Spring Boot стартер є формою автоматичного інструментування без програмування яке використовує spring autoconfigure для встановлення бібліотечного інструментування.

Дивіться Spring Boot стартер для отримання додаткової інформації.

Бібліотечне інструментування

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

Для списку бібліотек інструментування, дивіться колонку “Самостійні бібліотеки інструментування” у підтримуваних бібліотеках.

Нативне інструментування

Нативне інструментування вбудоване безпосередньо в бібліотеки або фреймворки. OpenTelemetry заохочує авторів бібліотек додавати нативне інструментування за допомогою API. У довгостроковій перспективі ми сподіваємося, що нативне інструментування стане нормою, і вигляд інструментування, яке підтримується OpenTelemetry в opentelemetry-java-instrumentation буде тимчасовим засобом заповнення прогалин.

• Elasticsearch Java API Client
• Quarkus

Ручне інструментування

Ручне інструментування написане авторами застосунків і зазвичай є специфічним для сфери використання застосунку.

Шими

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

Шими, які підтримуються в екосистемі OpenTelemetry Java:

Поширення контексту

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

Важливо, що дані з різних сигналів повʼязані між собою через контекст трасування:

• Відрізки повʼязані з іншими відрізками через батьківський відрізок і посилання, кожен з яких записує контекст трасування повʼязаних відрізків.
• Метрики повʼязані з відрізками через екземпляри, які записують контекст трасування конкретного вимірювання.
• Журнали повʼязані з відрізками шляхом запису контексту трасування в записи журналу.

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

• Бібліотеки, які представляють точку входу в застосунок (тобто HTTP сервери, споживачі повідомлень тощо) повинні видобувати контекст з вхідних повідомлень.
• Бібліотеки, які представляють точку виходу із застосунку (тобто HTTP клієнти, створювачі повідомлень тощо) повинні вставляти контекст у вихідні повідомлення.
• Бібліотеки повинні неявно або явно передавати Контекст через стек викликів і через будь-які потоки.

Семантичні домовленості

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

При написанні інструментування звертайтеся до семантичних конвенцій і дотримуйтесь будь-яких конвенцій, які застосовуються до домену.

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

Інструментування журналів

Хоча LoggerProvider / Logger API структурно схожі на еквівалентні trace та metric API, вони служать іншій меті. Зараз LoggerProvider / Logger та повʼязані класи представляють Log Bridge API, яке існує для написання доповнювачів логів для перенесення журналів, записаних через інші API логування / фреймворки в OpenTelemetry. Вони не призначені для кінцевих користувачів для використання як заміни для Log4j / SLF4J / Logback / тощо.

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

Безпосередньо в колектор

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

Щоб використовувати цей робочий процес:

• Встановіть відповідний доповнювач логів. [1]
• Налаштуйте OpenTelemetry Log SDK для експорту записів журналів до бажаного цільового місця призначення (колектора або іншого).

[1]: Доповнювачі логів є типом шима, який переносить журнали з системи логування в OpenTelemetry log SDK. Дивіться “Міст Log4j в OpenTelemetry”, “Міст Logback в OpenTelemetry” записи. Дивіться Приклад доповнювача логів для демонстрації різних сценаріїв.

Через файл або stdout

У робочому процесі журнали записуються у файли або стандартний вивід. Інший компонент (наприклад, FluentBit) відповідає за читання / відстеження журналів, їх розбір до більш структурованого формату та пересилання їх до місця призначення, такого як колектор. Цей робочий процес може бути кращим у ситуаціях, коли вимоги застосунку не дозволяють йому накладні витрати процесу безпосередньої передачі в колектор. Однак, він вимагає, щоб усі поля журналу, необхідні для подальшої обробки, були закодовані в журналах, і щоб компонент, який читає журнали, розбирав дані в модель даних журналів. Встановлення та налаштування компонентів для пересилання журналів виходить за рамки цього документа.

Кореляція журналів з трейсами доступна шляхом встановлення шима для перенесення контексту OpenTelemetry в систему логування. Дивіться “Міст OpenTelemetry контексту в Log4j”, “Міст OpenTelemetry контексту в Logback”.