Configuración del seguimiento en Azure SDK para Java

En este artículo se proporciona información general sobre cómo configurar Azure SDK para Java con el fin de integrar la funcionalidad de seguimiento.

Puede habilitar el seguimiento en las bibliotecas cliente de Azure usando y configurando el SDK de OpenTelemetry o mediante un agente compatible con OpenTelemetry. OpenTelemetry es un conocido marco de observabilidad de código abierto para generar, capturar y recopilar datos de telemetría para software nativo de nube.

Hay dos conceptos clave relacionados con el seguimiento: intervalo y seguimiento. Un intervalo representa una única operación en un seguimiento. Un intervalo puede representar una solicitud HTTP, una llamada a procedimiento remoto (RPC), una consulta de base de datos o incluso la ruta de acceso que toma el código. Un seguimiento es un árbol de intervalos que muestran la ruta de trabajo en un sistema. Puede distinguir un seguimiento propiamente dicho mediante una secuencia única de 16 bytes llamada TraceID. Para más información sobre estos conceptos y cómo se relacionan con OpenTelemetry, consulte la documentación de OpenTelemetry.

Seguimiento del SDK de Azure con el agente de Java de Azure Monitor

Con un agente de Java de Azure Monitor en el proceso, puede habilitar la supervisión de las aplicaciones sin necesidad de realizar cambios en el código. Para más información, consulte la Instrumentación automática basada en OpenTelemetry de Azure Monitor para aplicaciones Java. La compatibilidad con el SDK de Azure está habilitada de forma predeterminada a partir de la versión 3.2 del agente.

Seguimiento de llamadas del SDK de Azure con el agente de OpenTelemetry

Si usa el agente de Java de OpenTelemetry, la instrumentación del SDK de Azure está habilitada de forma predeterminada a partir de la versión 1.12.0.

Para obtener más información sobre cómo configurar exportadores, agregar instrumentación manual o enriquecer la telemetría, consulte Instrumentación de OpenTelemetry para Java.

Nota:

El artefacto del agente de OpenTelemetry es estable, pero no proporciona garantías de estabilidad de telemetría sobre la conexión, lo que puede provocar nombres de intervalo y nombres de atributo generados por Azure SDK que podrían cambiar con el tiempo si actualiza el agente. Para obtener más información, consulte Requisitos de compatibilidad.

Instrumentación manual de la aplicación con el SDK de OpenTelemetry (versión preliminar)

Si usa el SDK de OpenTelemetry directamente, asegúrese de configurar el SDK y el exportador para el back-end que prefiera. Para obtener más información, consulte la documentación de OpenTelemetry.

Para habilitar el seguimiento del SDK de Azure, agregue los paquetes com.azure:azure-core-tracing-opentelemetry más recientes a la aplicación. Por ejemplo, en Maven, agregue la siguiente entrada al archivo pom.xml:

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

Si ejecuta la aplicación ahora, debe obtener intervalos de Azure SDK en el back-end. Sin embargo, con las llamadas asincrónicas, es posible que se rompa la correlación entre el SDK de Azure y los intervalos de aplicaciones.

De forma predeterminada, el SDK de Azure usa io.opentelemetry.context.Context.current(), propagado implícitamente por OpenTelemetry, como elemento primario a intervalos nuevos. En llamadas asincrónicas, se interrumpe la propagación implícita del contexto. Los agentes de OpenTelemetry resuelven este problema al ayudar a propagar el contexto, pero el SDK de OpenTelemetry no tiene estas funcionalidades.

Pasar el contexto de seguimiento explícitamente

El SDK de Azure permite pasar el contexto de seguimiento explícitamente a través de com.azure.core.util.Context en la clave trace-context. Al proporcionar contexto de seguimiento explícito, el SDK de Azure lo usa en lugar del implícito, lo que permite la correlación entre intervalos de aplicación y SDK de Azure.

En el ejemplo siguiente, cuando se realiza un seguimiento manual de una solicitud web entrante, la biblioteca cliente de configuración de aplicaciones se llama de forma asincrónica en el ámbito de esta solicitud.

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

//...

Convenciones de seguimiento del SDK de Azure

Para averiguar qué intervalos y atributos emite el SDK, consulte la especificación de convenciones semánticas del SDK de Azure. Las convenciones semánticas del SDK de Azure (y OpenTelemetry) no son estables y pueden cambiar en el futuro.

Pasos siguientes

Ahora que está familiarizado con la funcionalidad básica transversal de Azure SDK para Java, consulte Autenticación de Azure con Java y Azure Identity para aprender a crear aplicaciones seguras.