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

  • Статья

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

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

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

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

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

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

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

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

Примечание.

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

Инструментирование приложения вручную с помощью пакета 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 позволяет явно передавать контекст трассировки с trace-context помощью com.azure.core.util.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, чтобы узнать, как создавать защищенные приложения.