Вступ до OpenTelemetry Java

OpenTelemetry Java — це набір інструментів спостереження OpenTelemetry для екосистеми Java. На високому рівні він складається з API, SDK та інструментів.

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

Огляд

API — це набір класів та інтерфейсів для запису телеметрії через ключові сигнали спостереження. Він підтримує кілька реалізацій, з невибагливим мінімалістичним Noop (тобто вимовляється “no-op”) та SDK референсною реалізацією, що надається з коробки. Він призначений бути прямою залежністю для бібліотек, фреймворків та власників застосунків, які хочуть додати інструментування. Він має сильні гарантії зворотної сумісності, нульові транзитивні залежності та підтримує Java 8+.

SDK — це вбудована референсна реалізація API, яка обробляє та експортує телеметрію, створену викликами API інструментування. Налаштування SDK для належної обробки та експорту є важливим кроком для інтеграції OpenTelemetry у застосунок. SDK має автоконфігурацію та програмні опції конфігурації.

Інструментування записує телеметрію за допомогою API. Існує кілька категорій інструментування, включаючи: агент Java без коду, стартер Spring Boot без коду, бібліотеку, native, керівництво shim.

Для огляду, незалежного від мови, дивіться концепції OpenTelemetry.

Навігація по документації

Документація OpenTelemetry Java організована наступним чином:

• Початок роботи на прикладі: Приклад для швидкого старту з OpenTelemetry Java, демонструючи інтеграцію агента OpenTelemetry Java у простий вебзастосунок.
• Екосистема інструментування: Керівництво по екосистемі інструментування OpenTelemetry Java. Це ключовий ресурс для авторів застосунків, які хочуть інтегрувати OpenTelemetry Java у свої застосунки. Дізнайтеся про різні категорії інструментування та виберіть, яка підходить вам.
• Запис телеметрії за допомогою API: Технічний довідник по API OpenTelemetry, що досліджує всі ключові аспекти API з робочими прикладами коду. Більшість користувачів використовуватимуть цю сторінку як енциклопедію, звертаючись до індексу розділів за потреби, а не читаючи від початку до кінця.
• Управління телеметрією за допомогою SDK: Технічний довідник по SDK OpenTelemetry, що досліджує всі точки розширення втулків SDK та програмний API конфігурації з робочими прикладами коду. Більшість користувачів використовуватимуть цю сторінку як енциклопедію, звертаючись до індексу розділів за потреби, а не читаючи від початку до кінця.
• Налаштування SDK: Технічний довідник по налаштуванню SDK, зосереджуючись на автоконфігурації без коду. Включає довідник по всіх підтримуваних змінних середовища та системних властивостях для налаштування SDK. Досліджує всі програмні точки налаштування з робочими прикладами коду. Більшість користувачів використовуватимуть цю сторінку як енциклопедію, звертаючись до індексу розділів за потреби, а не читаючи від початку до кінця.
• Дізнатися більше: Додаткові ресурси, включаючи приклади, Javadoc, компонент реєстр та довідник по продуктивності.

Репозиторії

Вихідний код OpenTelemetry Java організований у кілька репозиторіїв:

opentelemetry-java, opentelemetry-java-instrumentation та opentelemetry-java-contrib кожен публікує великі каталоги артефактів. Будь ласка, зверніться до репозиторіїв для деталей, або дивіться колонку “Керовані залежності” у таблиці Bill of Materials для повного списку керованих залежностей.

Як загальне правило, артефакти, опубліковані з одного репозиторію, мають однакову версію. Винятком є opentelemetry-java-contrib, який можна вважати групою незалежних проєктів, що співіснують в одному репозиторії для використання спільних інструментів. Наразі артефакти opentelemetry-java-contrib узгоджені, але це збіг і зміниться в майбутньому.

Репозиторії мають частоту випусків, яка відображає їхню високорівневу структуру залежностей:

• opentelemetry-java є ядром і випускається першим кожного місяця.
• opentelemetry-java-instrumentation залежить від opentelemetry-java і випускається наступним.
• opentelemetry-java-contrib залежить від opentelemetry-java-instrumentation та opentelemetry-java і випускається останнім.
• Хоча semantic-conventions-java є залежністю opentelemetry-java-instrumentation, це незалежний артефакт з незалежним графіком випусків.

Залежності та BOMs

Bill of materials, або BOM скорочено, це артефакт, який допомагає підтримувати версії повʼязаних залежностей узгодженими. OpenTelemetry Java публікує кілька BOMs, що відповідають різним випадкам використання, перелічених нижче в порядку зростання обсягу. Ми наполегливо рекомендуємо використовувати BOM.

Натисніть на посилання в колонці “Керовані залежності”, щоб побачити список артефактів, керованих BOM.

Наступний фрагмент коду демонструє додавання залежності BOM, з{{bomGroupId}}, {{bomArtifactId}} та {{bomVersion}}, що відносяться до колонок таблиці “Group ID”, “Artifact ID” та “Current Version”, відповідно.

• Gradle
• Maven

dependencies {
  implementation(platform("{{bomGroupId}}:{{bomArtifactId}}:{{bomVersion}}"))
  // Додайте залежність від артефакту, версія якого керується BOM
  implementation("io.opentelemetry:opentelemetry-api")
}

<project>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>{{bomGroupId}}</groupId>
        <artifactId>{{bomArtifactId}}</artifactId>
        <version>{{bomVersion}}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <!-- Додайте залежність від артефакту, версія якого керується BOM -->
  <dependencies>
    <dependency>
      <groupId>io.opentelemetry</groupId>
      <artifactId>opentelemetry-api</artifactId>
    </dependency>
  </dependencies>
</project>