Автоматическое инструментирование Azure Monitor на основе OpenTelemetry для приложений Java

  • Статья
  • Чтение занимает 10 мин

Эта статья описывает, как включить и настроить предложение Azure Monitor на основе OpenTelemetry для Java. Ее можно использовать для любой среды, включая локальную. После выполнения инструкций, описанных в этой статье, вы можете использовать Azure Monitor Application Insights для мониторинга приложения.

Примечание

Поддержка приема ключей инструментирования будет завершена 31 марта 31, 2025 г. Функция продолжит работать, но не будет обновляться или поддерживаться. Перейдите на строки подключения, чтобы использовать новые возможности.

Начало работы

Автоматическое инструментирование Java включается путем изменения конфигурации. Изменения кода не требуются.

Предварительные требования

Вам необходимы:

Включение Application Insights в Azure Monitor

В этом разделе показано, как скачать JAR-файл автоматического инструментирования.

Скачивание JAR-файла

Скачайте файл applicationinsights-agent-3.4.8.jar .

Предупреждение

При обновлении с более ранней версии 3.x на вас могут повлиять изменения по умолчанию или небольшие различия в собираемых нами данных. Дополнительные сведения см. в заметках о миграции для версий 3.4.0, 3.3.0, 3.2.0 и 3.1.0 .

Указание виртуальной машине Java на JAR-файл

Добавьте -javaagent:"path/to/applicationinsights-agent-3.4.8.jar" в аргумент виртуальной машина Java вашего приложения.

Совет

Дополнительные сведения о настройке аргументов виртуальной машины Java для приложения см. в статье Советы по обновлению аргументов виртуальной машины Java.

Если вы разрабатываете приложение Spring Boot, вы можете заменить аргумент JVM программной конфигурацией. Дополнительные сведения см. в статье Использование Azure Monitor Application Insights с Spring Boot.

Задание строки подключения Application Insights

  1. Указать на ресурс Application Insights для JAR-файла можно двумя способами:

    • Задайте переменную среды:

      APPLICATIONINSIGHTS_CONNECTION_STRING=<Copy connection string from Application Insights Resource Overview>

    • Создайте файл конфигурации с именем applicationinsights.json. Поместите его в тот же каталог, что и applicationinsights-agent-3.4.8.jar, и добавьте в него следующее содержимое:

      {
  "connectionString": "Copy connection string from Application Insights Resource Overview"
}

  2. Найдите строку подключения в ресурсе Application Insights.

    Снимок экрана: строка подключения и обзор Application Insights.

Подтверждение передачи данных

Запустите приложение и откройте вкладку Ресурс Application Insights на портале Azure. Отображение данных на портале может занять несколько минут.

Примечание

Если не удается запустить приложение или получить данные ожидаемым образом, см. раздел Устранение неполадок.

Снимок экрана: вкладка обзора Application Insights с запросом к серверу и временем ответа сервера.

Важно!

При наличии двух или более служб, которые выводят данные телеметрии в один и тот же ресурс Application Insights, необходимо задать имена облачных ролей, чтобы правильно представить их на схеме приложений.

В рамках использования инструментирования Application Insights мы собираем диагностические данные и отправляем их в корпорацию Майкрософт. Эти данные помогают нам использовать и улучшать Application Insights. Вы можете отключить сбор несущественных данных. Дополнительные сведения см. в разделе Statsbeat в Azure Application Insights.

Варианты настройки

В файле applicationinsights.json также можно настроить следующие параметры:

  • Имя облачной роли
  • Экземпляр облачной роли
  • Дискретизация
  • Метрики JMX
  • Пользовательские измерения
  • Обработчики данных телеметрии (предварительная версия)
  • Автоматически собранные журналы
  • Автоматически собранные метрики микрометров, включая метрики Spring Boot Actuator
  • Пульс
  • Прокси-сервер HTTP
  • Самодиагностика

Дополнительные сведения см. в разделе Параметры конфигурации.

Автоматическое инструментирование

Java 3.x включает указанные ниже библиотеки автоматического инструментирования.

Автоматически собранные запросы

  • Потребители JMS
  • Потребители Kafka
  • Нетти
  • Quartz
  • Сервлеты
  • Планирование Spring

Примечание

Сервлет и автоматическое инструментирование Netty охватывают большинство служб HTTP Java, включая Java EE, Jakarta EE, Spring Boot, Quarkus и Micronaut.

Автоматически собранные зависимости

Автоматически собранные зависимости и нисходящее распространение распределенной трассировки:

  • Apache HttpClient
  • Apache HttpAsyncClient
  • AsyncHttpClient
  • Google HttpClient
  • gRPC
  • java.net.HttpURLConnection
  • Java 11 HttpClient
  • Клиент JAX-RS
  • Jetty HttpClient
  • JMS
  • Kafka
  • Клиент Netty
  • OkHttp;

Автоматически собранные зависимости без нисходящего распространения распределенной трассировки:

  • Cassandra
  • JDBC
  • MongoDB (Async и Sync)
  • Redis (Lettuce и Jedis)

Автоматически собранные журналы

  • Logback (включая свойства MDC)
  • Log4j (включая свойства MDC/Thread Context)
  • Ведение журнала JBoss (включая свойства MDC)
  • java.util.logging

Автоматически собранные метрики

  • Микрометр, включая метрики Spring Boot Actuator
  • Метрики JMX

Пакеты Azure SDK

Данные телеметрии, выводимые этими пакетами Azure SDK, по умолчанию собираются автоматически:

Изменение телеметрии

В этом разделе описано, как изменить телеметрию.

Добавление диапазонов с помощью заметки OpenTelemetry

Самый простой способ добавить собственные диапазоны — использовать заметку @WithSpan OpenTelemetry.

Диапазоны заполняют таблицы requests и dependencies в Application Insights.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-instrumentation-annotations-1.21.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-instrumentation-annotations</artifactId>
  <version>1.21.0</version>
</dependency>

  2. Используйте заметку @WithSpan, чтобы создавать интервал при каждом выполнении метода:

     import io.opentelemetry.instrumentation.annotations.WithSpan;

 @WithSpan(value = "your span name")
 public void yourMethod() {
 }

По умолчанию диапазон окажется в таблице с типом dependenciesInProcзависимости .

Если метод представляет фоновое задание, которое еще не захвачено автоматическим инструментированием, рекомендуется применить атрибут kind = SpanKind.SERVER к заметке @WithSpan , чтобы он попал в таблицу Application Insights requests .

Добавление диапазонов с помощью API OpenTelemetry

Если предыдущая заметка OpenTelemetry @WithSpan не соответствует вашим потребностям, вы можете добавить диапазоны с помощью API OpenTelemetry.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. GlobalOpenTelemetry Используйте класс для создания Tracer:

     import io.opentelemetry.api.GlobalOpenTelemetry;
 import io.opentelemetry.api.trace.Tracer;

 static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");

  3. Создайте диапазон, сделайте его текущим, а затем завершите его:

     Span span = tracer.spanBuilder("my first span").startSpan();
 try (Scope ignored = span.makeCurrent()) {
     // do stuff within the context of this 
 } catch (Throwable t) {
     span.recordException(t);
 } finally {
     span.end();
 }

Добавление событий диапазона

Вы можете использовать для opentelemetry-api создания событий диапазона, которые заполняют таблицу traces в Application Insights. Строка, передаваемая в , addEvent() сохраняется в message поле трассировки.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Добавьте события диапазона в код:

     import io.opentelemetry.api.trace.Span;

 Span.current().addEvent("eventName");

Добавление атрибутов диапазона

Для добавления атрибутов в диапазоны можно использовать opentelemetry-api. Эти атрибуты могут включать в себя добавление пользовательского бизнес-измерения в данные телеметрии. Можно также использовать атрибуты для задания необязательных полей в схеме Application Insights, таких как "Идентификатор пользователя" или "IP-адрес клиента".

Добавление одного или нескольких атрибутов span заполняет customDimensions поле в requestsтаблице , dependencies, tracesили exceptions .

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Добавьте настраиваемые измерения в код:

     import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.common.AttributeKey;

 AttributeKey attributeKey = AttributeKey.stringKey("mycustomdimension");
 Span.current().setAttribute(attributeKey, "myvalue1");

Обновление состояния диапазона и исключений записей

Можно использовать opentelemetry-api для обновления состояния исключений диапазона и записи.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Задайте состояние error и запишите исключение в коде:

     import io.opentelemetry.api.trace.Span;
 import io.opentelemetry.api.trace.StatusCode;

 Span span = Span.current();
 span.setStatus(StatusCode.ERROR, "errorMessage");
 span.recordException(e);

Задание идентификатора пользователя

user ID Заполните поле в requestsтаблице , dependenciesили exceptions .

Ознакомьтесь с применимыми законами о конфиденциальности, прежде чем задавать идентификатор пользователя, прошедшего проверку подлинности.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Задайте user_Id в коде:

    import io.opentelemetry.api.trace.Span;

Span.current().setAttribute("enduser.id", "myuser");

Получение идентификатора трассировки или идентификатора диапазона

Для получения идентификатора трассировки или идентификатора диапазона можно использовать opentelemetry-api. Это действие можно выполнить, чтобы добавить эти идентификаторы в существующую телеметрию журнала, чтобы улучшить корреляцию при отладке и диагностике проблем.

Примечание

Эта функция доступна только в версии 3.2.0 и более поздних.

  1. Добавьте opentelemetry-api-1.0.0.jar в приложение (или более позднюю версию):

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.0.0</version>
</dependency>

  2. Получите идентификатор трассировки запроса и идентификатор диапазона в коде:

    import io.opentelemetry.api.trace.Span;

Span span = Span.current();
String traceId = span.getSpanContext().getTraceId();
String spanId = span.getSpanContext().getSpanId();

Пользовательская телеметрия

Наша цель в Application Insights Java 3.x — обеспечить возможность отправки пользовательской телеметрии с помощью стандартных API.

В настоящее время мы поддерживаем Micrometer, популярные платформы ведения журнала и классический пакет SDK Для Java для Application Insights. В Application Insights Java 3.x данные телеметрии, отправляемые через эти API, захватываются автоматически и сопоставляются с автоматически собираемой телеметрией.

Поддерживаемые пользовательские типы телеметрии

Приведенная ниже таблица представляет поддерживаемые на данный момент пользовательские типы телеметрии, которые можно включить в дополнение к работе агента Java 3.x. Подведение итогов.

  • Пользовательские метрики поддерживаются с помощью Micrometer.
  • Пользовательские исключения и трассировки поддерживаются через платформы ведения журналов.
  • Пользовательские запросы, зависимости, метрики и исключения поддерживаются через API OpenTelemetry.
  • Остальные типы телеметрии поддерживаются с помощью классического пакета SDK для Application Insights.
Тип пользовательской телеметрии Micrometer Logback, Log4j, JUL OpenTelemetry API Классический пакет SDK
Настраиваемые события Да
Настраиваемые метрики Да Да Да
Зависимости Да Да
Исключения Да Да Да
Просмотры страниц Да
Requests Да Да
Трассировки Да Да

Отправка пользовательских метрик с помощью Micrometer

  1. Добавьте Micrometer к вашему приложению:

    <dependency>
  <groupId>io.micrometer</groupId>
  <artifactId>micrometer-core</artifactId>
  <version>1.6.1</version>
</dependency>

  2. Используйте глобальный реестр Micrometer для создания счетчика:

    static final Counter counter = Metrics.counter("test.counter");

  3. Используйте счетчик для записи метрик:

    counter.increment();

  4. Метрики будут приняты в таблицу customMetrics с тегами, захваченными в столбце customDimensions. Вы также можете просмотреть метрики в обозревателе метрик в Log-based metrics пространстве имен метрик.

    Примечание

    Java Application Insights заменяет все небуквенно-цифровые символы (кроме дефисов) в имени метрики Micrometer символами подчеркивания. В результате предыдущая test.counter метрика будет отображаться как test_counter.

Отправка пользовательских трассировок и исключений с помощью выбранной платформы ведения журналов

Logback, Log4j и java.util.logging автоматически инструментируются. Ведение журналов с их помощью подвергается автоматическому сбору в виде телеметрии трассировок и исключений.

По умолчанию ведение журнала собирается только в том случае, если ведение журнала выполняется на уровне INFO или выше. Чтобы изменить этот уровень, см. раздел Параметры конфигурации.

Структурированное ведение журнала (присоединение пользовательских измерений к журналам) можно выполнить следующим образом:

Отправка пользовательских данных телеметрии с помощью классического пакета SDK для Application Insights

  1. Добавьте applicationinsights-core в свое приложение:

    <dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>3.4.8</version>
</dependency>

  2. Создайте экземпляр TelemetryClient:

    static final TelemetryClient telemetryClient = new TelemetryClient();

  3. Используйте клиент для отправки пользовательской телеметрии:

    События
    telemetryClient.trackEvent("WinGame");
    Метрики
    telemetryClient.trackMetric("queueLength", 42.0);
    Зависимости
    boolean success = false;
long startTime = System.currentTimeMillis();
try {
    success = dependency.call();
} finally {
    long endTime = System.currentTimeMillis();
    RemoteDependencyTelemetry telemetry = new RemoteDependencyTelemetry();
    telemetry.setSuccess(success);
    telemetry.setTimestamp(new Date(startTime));
    telemetry.setDuration(new Duration(endTime - startTime));
    telemetryClient.trackDependency(telemetry);
}
    Журналы
    telemetryClient.trackTrace(message, SeverityLevel.Warning, properties);
    Исключения
    try {
    ...
} catch (Exception e) {
    telemetryClient.trackException(e);
}

Устранение неполадок

См. специальные инструкции по устранению неполадок.

Проверка подключения между узлом приложения и службой приема

Пакеты SDK и агенты Application Insights отправляют данные телеметрии для приема в качестве вызовов REST к конечным точкам приема. Вы можете проверить подключение веб-сервера или хост-компьютера приложения к конечным точкам службы приема с помощью необработанных клиентов REST из PowerShell или команд curl. См. статью Устранение неполадок с отсутствующими данными телеметрии приложений в Azure Monitor Application Insights.

Заметки о выпуске

См. заметки о выпуске на GitHub.

Поддержка

Для получения поддержки сделайте следующее:

Обратная связь с OpenTelemetry

Чтобы оставить отзыв, сделайте следующее:

Дальнейшие действия