Настройка трассировки в Azure SDK для Java

В этой статье приведены общие сведения о настройке пакета Azure SDK для Java для внедрения возможностей трассировки.

Вы можете включить трассировку в клиентских библиотеках Azure с помощью пакета SDK OpenTelemetry или с помощью агента, совместимого с OpenTelemetry. OpenTelemetry — это популярная платформа наблюдаемости с открытым кодом для создания, записи и сбора данных телеметрии для ориентированного на облако программного обеспечения.

С трассировкой связаны два основных понятия: span и trace. Span представляет собой одну операцию в процессе trace. Это может быть HTTP-запрос, удаленный вызов процедуры (RPC), запрос базы данных или даже путь, который принимается кодом. Тrace — это дерево операций span, отображающее ход операций в системе. Трейс можно отличить по уникальной 16-байтовой последовательности, которая называется TraceID. Дополнительные сведения об этих понятиях и их связи с OpenTelemetry см. в документации по OpenTelemetry.

Трассировка пакета SDK Azure с помощью агента Java Azure Monitor

С помощью агента Java в процессе Azure Monitor можно включить мониторинг приложений без каких-либо изменений кода. Дополнительные сведения см. в разделе «Автоматическое инструментирование Azure Monitor на основе OpenTelemetry для приложений Java». Поддержка пакета SDK для Azure включена по умолчанию, начиная с агента версии 3.2.

Трассировка вызовов SDK Azure с помощью агента OpenTelemetry

Если вы используете агент OpenTelemetry для Java, поддержка инструментирования SDK Azure включена по умолчанию, начиная с версии 1.12.0.

Дополнительные сведения о настройке экспортеров, добавлении ручной инструментализации или обогащении телеметрии см. в статье OpenTelemetry Instrumentation for Java.

Инструментирование приложения вручную с помощью пакета SDK OpenTelemetry (предварительная версия)

Если вы используете пакет SDK OpenTelemetry напрямую, обязательно настройте пакет SDK и экспортер для выбранной серверной части. Для получения дополнительной информации, см. документацию OpenTelemetry.

Чтобы включить трассировку SDK Azure, добавьте в приложение последние пакеты com.azure:azure-core-tracing-opentelemetry. Например, в Maven добавьте следующую запись в файл pom.xml :

<dependency>
  <groupId>com.azure</groupId>
  <artifactId>azure-core-tracing-opentelemetry</artifactId>
</dependency>

Если вы запускаете приложение сейчас, вы должны получить диапазоны azure SDK на серверной части. Однако при асинхронных вызовах корреляция между пакетом SDK Azure и диапазонами приложений может быть нарушена.

По умолчанию SDK Azure использует io.opentelemetry.context.Context.current(), который неявно передается OpenTelemetry, в качестве родителя для новых интервалов. В асинхронных вызовах неявное распространение контекста прерывается. Агенты OpenTelemetry решают эту проблему, помогая распространять контекст, но пакет SDK OpenTelemetry не имеет таких возможностей.

Непосредственно передать контекст трассировки

Пакет SDK Azure позволяет явно передавать контекст трассировки через com.azure.core.util.Context под ключом trace-context. Если вы предоставляете явный контекст трассировки, пакет SDK Azure использует его вместо неявного, что обеспечивает корреляцию между приложениями и пакетами SDK Azure.

В следующем примере при трассировке входящего веб-запроса клиентская библиотека конфигурации приложений вызывается асинхронно в области этого запроса.

Span span = TRACER.spanBuilder("incoming request").startSpan();
io.opentelemetry.context.Context traceContext = io.opentelemetry.context.Context.root().with(span);

// Put the incoming-request span (wrapped into the OpenTelemetry Context) into the Azure SDK Context
// and pass it over to the Application Configuration call.
appConfigClient.setConfigurationSettingWithResponse(settings, true, new com.azure.core.util.Context("trace-context", traceContext));

// You could also pass the context using the reactor `contextWrite` method under the same `trace-context` key.
appConfigAsyncClient.setConfigurationSettingWithResponse(settings)
   .contextWrite(reactor.util.context.Context.of("trace-context", traceContext))

//...

Соглашения о трассировке пакета SDK Для Azure

Чтобы узнать, какие диапазоны и атрибуты выпускает SDK, см. спецификацию семантических соглашений Azure SDK. Семантические соглашения SDK Azure (и OpenTelemetry) не стабильны и могут измениться в будущем.

Следующие шаги

Теперь, когда вы имеете представление об основных сквозных функциях в пакете Azure SDK для Java, ознакомьтесь со статьей Аутентификация в Azure с помощью Java и удостоверений Azure, чтобы узнать, как создавать защищенные приложения.