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

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

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

Двумя ключевыми понятиями, связанными с трассировкой, являются диапазон и трассировка. 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.

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

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

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

Примечание.

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

Инструментирование приложения вручную с помощью пакета 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 на серверной части. Однако при асинхронных вызовах корреляция между Azure SDK и диапазонами приложений может быть нарушена.

По умолчанию 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. Семантические соглашения Azure SDK (и OpenTelemetry) нестабильны и могут измениться в будущем.

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

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

  • Last updated on