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

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

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

Примечание

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

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

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

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

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

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

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

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

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

При обновлении с более ранней версии 3.x

Начиная с версии 3.4.0:

  • Выборка с ограниченной скоростью теперь используется по умолчанию (если вы ранее не настроили фиксированный процент). По умолчанию записывается не более 5 запросов в секунду (наряду с их зависимостями, трассировками и пользовательскими событиями). Если вы хотите вернуться к предыдущему поведению и записывать 100 % запросов, см. выборку с фиксированным процентом.

Начиная с версии 3.3.0:

  • LoggingLevel по умолчанию не записывается как часть настраиваемого измерения трассировки, так как эти данные уже записаны в поле SeverityLevel. Дополнительные сведения о том, как повторно включить эту функцию при необходимости, можно найти в описании параметров конфигурации.
  • Записи исключений больше не записываются для неудачных зависимостей, они записываются только для неудачных запросов.

Начиная с версии 3.2.0:

  • Зависимости контроллера InProc больше не записываются по умолчанию. Дополнительные сведения о том, как повторно включить эту функцию, можно найти в описании параметров конфигурации.
  • Имена зависимостей базы данных теперь стали более лаконичными, при этом полный (очищенный) запрос все еще содержится в поле data. Имена зависимостей HTTP теперь стали более описательными. Это изменение может повлиять на настраиваемые панели мониторинга или оповещения, если в них применяются предыдущие значения. Дополнительные сведения см. в заметках о выпуске 3.2.0.

Начиная с версии 3.1.0:

  • Имена операций и телеметрии запросов теперь имеют префикс, соответствующий методу HTTP, например, GET и POST. Это изменение может повлиять на настраиваемые панели мониторинга или оповещения, если в них применяются предыдущие значения. Дополнительные сведения см. в заметках о выпуске 3.1.0.

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

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

Совет

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

Совет

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

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

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

    • Можно задать переменную среды:

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

    • Или можно создать файл конфигурации с именем applicationinsights.json. Поместите его в тот же каталог, что и applicationinsights-agent-3.4.4.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
  • Пользовательские измерения
  • Обработчики данных телеметрии (предварительная версия)
  • Автоматически собранные журналы
  • Автоматически собранные метрики Micrometer, включая метрики Spring Boot Actuator
  • Пульс
  • Прокси-сервер HTTP
  • Самодиагностика

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

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

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

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

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

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

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

  • 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)

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

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

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

  • Micrometer, включающий в себя метрики Spring Boot Actuator
  • Метрики JMX

Пакеты Azure SDK

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

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

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

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

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

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

Примечание

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

  1. Добавьте opentelemetry-extension-annotations-1.16.0.jar в свое приложение:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-extension-annotations</artifactId>
  <version>1.16.0</version>
</dependency>

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

     import io.opentelemetry.extension.annotations.WithSpan;

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

По умолчанию интервал переносится в таблицу зависимостей с типом зависимости InProc.

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

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

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

Примечание

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

  1. Добавьте opentelemetry-api-1.6.0.jar в свое приложение:

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

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

     import io.opentelemetry.api.trace.Span;

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

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

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

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

Примечание

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

  1. Добавьте opentelemetry-api-1.6.0.jar в свое приложение:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.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.6.0.jar в свое приложение:

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

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

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

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

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

Заполните поле Идентификатор пользователя в таблице запросов, зависимостей или исключений.

Важно!

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

Примечание

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

  1. Добавьте opentelemetry-api-1.6.0.jar в свое приложение:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.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.6.0.jar в свое приложение:

    <dependency>
  <groupId>io.opentelemetry</groupId>
  <artifactId>opentelemetry-api</artifactId>
  <version>1.6.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 для Application Insights Java версии 2.x. В Application Insights Java 3.x данные телеметрии, отправляемые через эти API, захватываются автоматически и сопоставляются с автоматически собираемой телеметрией.

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

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

  • Пользовательские метрики поддерживаются через Micrometer.
  • Пользовательские исключения и трассировки поддерживаются через платформы ведения журналов.
  • Пользовательские запросы, зависимости, метрики и исключения поддерживаются через opentelemetry-api.
  • Все типы пользовательской телеметрии поддерживаются с помощью пакета SDK для Application Insights Java 2.x.
Тип пользовательской телеметрии Micrometer Log4j, logback, ИЮЛ SDK версии 2.x opentelemetry-api
Настраиваемые события Да
Настраиваемые метрики Да Да Да
Зависимости Да Да
Исключения Да Да Да
Просмотры страниц Да
Requests Да Да
Трассировки Да Да

В настоящее время мы не планируем выпускать пакет SDK с Application Insights 3.x.

Application Insights Java 3.x уже прослушивает данные телеметрии, отправляемые в пакет SDK Application Insights Java 2.x. Эта функция является важной частью истории обновления для существующих пользователей версии 2.x. Кроме того, она помогает заполнить серьезный пробел в нашей реализации пользовательской телеметрии до тех пор, пока все пользовательские типы телеметрии не будут реализованы через API OpenTelemetry.

Отправка пользовательских метрик с помощью 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. Метрики можно также просмотреть в обозревателе метрик в пространстве имен метрик "Метрики на основе журнала".

    Примечание

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

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

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

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

Если вы хотите присоединить пользовательские измерения к журналам, используйте Log4j 1.2 MDC, Log4j 2 MDC или Logback MDC. Application Insights Java 3.x автоматически захватит эти свойства MDC в виде пользовательских измерений в телеметрии трассировок и исключений.

Отправка пользовательской телеметрии с помощью пакета SDK для версии 2.x

  1. Добавьте applicationinsights-core-2.6.4.jar в свое приложение. В Application Insights Java 3.x поддерживаются все версии 2.x. Если у вас есть выбор, стоит использовать последнюю версию:

    <dependency>
  <groupId>com.microsoft.azure</groupId>
  <artifactId>applicationinsights-core</artifactId>
  <version>2.6.4</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

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

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