Автоматическое инструментирование Azure Monitor на основе OpenTelemetry для приложений Java
Эта статья описывает, как включить и настроить предложение Azure Monitor на основе OpenTelemetry для Java. Ее можно использовать для любой среды, включая локальную. После выполнения инструкций, описанных в этой статье, вы можете использовать Azure Monitor Application Insights для мониторинга приложения.
Примечание
Поддержка приема ключей инструментирования будет завершена 31 марта 31, 2025 г. Функция продолжит работать, но не будет обновляться или поддерживаться. Перейдите на строки подключения, чтобы использовать новые возможности.
Начало работы
Автоматическое инструментирование Java включается путем изменения конфигурации. Изменения кода не требуются.
Предварительные требования
Вам необходимы:
- Приложение Java, использующее Java 8+.
- Подписка Azure. Создайте бесплатную подписку Azure.
- Ресурс Application Insights. Создайте ресурс Application Insights.
Включение 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
Указать на ресурс 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" }
Найдите строку подключения в ресурсе Application Insights.
Подтверждение передачи данных
Запустите приложение и откройте вкладку Ресурс Application Insights на портале Azure. Отображение данных на портале может занять несколько минут.
Примечание
Если не удается запустить приложение или получить данные ожидаемым образом, см. раздел Устранение неполадок.
Важно!
При наличии двух или более служб, которые выводят данные телеметрии в один и тот же ресурс 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, по умолчанию собираются автоматически:
- Конфигурация приложений Azure 1.1.10 или более поздней версии
- Когнитивный поиск Azure 11.3.0 или более поздней версии
- Службы коммуникации Azure — чат 1.0.0 или более поздней версии
- Службы коммуникации Azure — общее 1.0.0 или более поздней версии
- Службы коммуникации Azure — удостоверение 1.0.0 или более поздней версии
- Службы коммуникации Azure — номера телефонов 1.0.0 или более поздней версии
- Службы коммуникации Azure — SMS 1.0.0 или более поздней версии
- Azure Cosmos DB 4.22.0+
- Azure Digital Twins — основные компоненты 1.1.0 или более поздней версии
- Сетка событий Azure 4.0.0 или более поздней версии
- Центры событий Azure 5.6.0 или более поздней версии
- Центры событий Azure — хранилище контрольных точек Хранилища BLOB-объектов Azure 1.5.1 или более поздней версии
- Распознаватель документов Azure 3.0.6 или более поздней версии
- Идентификация Azure 1.2.4 или более поздней версии
- Azure Key Vault — сертификаты 4.1.6 или более поздней версии
- Azure Key Vault — ключи 4.2.6 или более поздней версии
- Azure Key Vault — секреты 4.2.6 или более поздней версии
- Служебная шина Azure 7.1.0 или более поздней версии
- Служба хранилища Azure — BLOB-объекты 12.11.0 или более поздней версии
- Служба хранилища Azure — пакет BLOB-объектов 12.9.0 или более поздней версии
- Служба хранилища Azure — шифрование BLOB-объектов 12.11.0 или более поздней версии
- Служба хранилища Azure — общее 12.11.0 или более поздней версии
- Служба хранилища Azure — озеро данных для файлов 12.5.0 или более поздней версии
- Служба хранилища Azure — общие папки 12.9.0 или более поздней версии
- Служба хранилища Azure — очереди 12.9.0 или более поздней версии
- Анализ текста Azure 5.0.4 или более поздней версии
Изменение телеметрии
В этом разделе описано, как изменить телеметрию.
Добавление диапазонов с помощью заметки OpenTelemetry
Самый простой способ добавить собственные диапазоны — использовать заметку @WithSpan
OpenTelemetry.
Диапазоны заполняют таблицы requests
и dependencies
в Application Insights.
Примечание
Эта функция доступна только в версии 3.2.0 и более поздних.
Добавьте
opentelemetry-instrumentation-annotations-1.21.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-instrumentation-annotations</artifactId> <version>1.21.0</version> </dependency>
Используйте заметку
@WithSpan
, чтобы создавать интервал при каждом выполнении метода:import io.opentelemetry.instrumentation.annotations.WithSpan; @WithSpan(value = "your span name") public void yourMethod() { }
По умолчанию диапазон окажется в таблице с типом dependencies
InProc
зависимости .
Если метод представляет фоновое задание, которое еще не захвачено автоматическим инструментированием, рекомендуется применить атрибут kind = SpanKind.SERVER
к заметке @WithSpan
, чтобы он попал в таблицу Application Insights requests
.
Добавление диапазонов с помощью API OpenTelemetry
Если предыдущая заметка OpenTelemetry @WithSpan
не соответствует вашим потребностям, вы можете добавить диапазоны с помощью API OpenTelemetry.
Примечание
Эта функция доступна только в версии 3.2.0 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
GlobalOpenTelemetry
Используйте класс для созданияTracer
:import io.opentelemetry.api.GlobalOpenTelemetry; import io.opentelemetry.api.trace.Tracer; static final Tracer tracer = GlobalOpenTelemetry.getTracer("com.example");
Создайте диапазон, сделайте его текущим, а затем завершите его:
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 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
Добавьте события диапазона в код:
import io.opentelemetry.api.trace.Span; Span.current().addEvent("eventName");
Добавление атрибутов диапазона
Для добавления атрибутов в диапазоны можно использовать opentelemetry-api
. Эти атрибуты могут включать в себя добавление пользовательского бизнес-измерения в данные телеметрии. Можно также использовать атрибуты для задания необязательных полей в схеме Application Insights, таких как "Идентификатор пользователя" или "IP-адрес клиента".
Добавление одного или нескольких атрибутов span заполняет customDimensions
поле в requests
таблице , dependencies
, traces
или exceptions
.
Примечание
Эта функция доступна только в версии 3.2.0 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
Добавьте настраиваемые измерения в код:
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 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
Задайте состояние
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 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
Задайте
user_Id
в коде:import io.opentelemetry.api.trace.Span; Span.current().setAttribute("enduser.id", "myuser");
Получение идентификатора трассировки или идентификатора диапазона
Для получения идентификатора трассировки или идентификатора диапазона можно использовать opentelemetry-api
. Это действие можно выполнить, чтобы добавить эти идентификаторы в существующую телеметрию журнала, чтобы улучшить корреляцию при отладке и диагностике проблем.
Примечание
Эта функция доступна только в версии 3.2.0 и более поздних.
Добавьте
opentelemetry-api-1.0.0.jar
в приложение (или более позднюю версию):<dependency> <groupId>io.opentelemetry</groupId> <artifactId>opentelemetry-api</artifactId> <version>1.0.0</version> </dependency>
Получите идентификатор трассировки запроса и идентификатор диапазона в коде:
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
Добавьте Micrometer к вашему приложению:
<dependency> <groupId>io.micrometer</groupId> <artifactId>micrometer-core</artifactId> <version>1.6.1</version> </dependency>
Используйте глобальный реестр Micrometer для создания счетчика:
static final Counter counter = Metrics.counter("test.counter");
Используйте счетчик для записи метрик:
counter.increment();
Метрики будут приняты в таблицу customMetrics с тегами, захваченными в столбце
customDimensions
. Вы также можете просмотреть метрики в обозревателе метрик вLog-based metrics
пространстве имен метрик.Примечание
Java Application Insights заменяет все небуквенно-цифровые символы (кроме дефисов) в имени метрики Micrometer символами подчеркивания. В результате предыдущая
test.counter
метрика будет отображаться какtest_counter
.
Отправка пользовательских трассировок и исключений с помощью выбранной платформы ведения журналов
Logback, Log4j и java.util.logging автоматически инструментируются. Ведение журналов с их помощью подвергается автоматическому сбору в виде телеметрии трассировок и исключений.
По умолчанию ведение журнала собирается только в том случае, если ведение журнала выполняется на уровне INFO или выше. Чтобы изменить этот уровень, см. раздел Параметры конфигурации.
Структурированное ведение журнала (присоединение пользовательских измерений к журналам) можно выполнить следующим образом:
- Восстановление журнала MDC
- Log4j 2 MapMessage (
MapMessage
ключ"message"
будет записан в виде сообщения журнала) - Контекст потока Log4j 2
- Log4j 1.2 MDC
Отправка пользовательских данных телеметрии с помощью классического пакета SDK для Application Insights
Добавьте
applicationinsights-core
в свое приложение:<dependency> <groupId>com.microsoft.azure</groupId> <artifactId>applicationinsights-core</artifactId> <version>3.4.8</version> </dependency>
Создайте экземпляр
TelemetryClient
:static final TelemetryClient telemetryClient = new TelemetryClient();
Используйте клиент для отправки пользовательской телеметрии:
События
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.
Поддержка
Для получения поддержки сделайте следующее:
- Чтобы получить справочные сведения об устранении неполадок, см. описание шагов по устранению неполадок.
- Чтобы получить сведения о проблемах поддержки Azure, сделайте запрос в службу поддержки Azure.
- При проблемах с OpenTelemetry обратитесь непосредственно к сообществу OpenTelemetry.
Обратная связь с OpenTelemetry
Чтобы оставить отзыв, сделайте следующее:
- Пройдите опрос для сбора отзывов клиентов в сообществе OpenTelemetry.
- Сообщите корпорации Майкрософт о себе, присоединившись к нашему сообществу ранних последователей OpenTelemetry.
- Общайтесь с другими пользователями Azure Monitor в Microsoft Tech Community.
- Выполните запрос на функцию на форуме отзывов Azure.
Дальнейшие действия
- Просмотрите параметры конфигурации автоматического инструментирования Java.
- Чтобы просмотреть исходный код, см. репозиторий автоматического инструментирования Java для Azure Monitor на GitHub.
- Чтобы получить дополнительные сведения о OpenTelemetry и соответствующем сообществе см. репозиторий Java для OpenTelemetry на GitHub.
- Чтобы включить функции использования, см. раздел о включении наблюдения за пользователями в Интернете или обозревателе.