Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
En este artículo se proporciona información general sobre cómo configurar SDK de Azure para Java con el fin de integrar la funcionalidad de seguimiento.
Puede habilitar el seguimiento en las bibliotecas cliente de Azure mediante el uso y la configuración del SDK de OpenTelemetry o mediante el uso de 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.
Dos conceptos clave relacionados con el trazado son span y traza. Un segmento representa una única operación en una traza. 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. Una secuencia única de 16 bytes llamada TraceID distingue una traza. 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 obtener más información, consulte la instrumentación automática basada en OpenTelemetry para aplicaciones Java de Azure Monitor. La compatibilidad con el SDK de Azure está habilitada de forma predeterminada a partir de la versión 3.2 del agente.
Trazabilidad de 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 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 ofrece garantías de estabilidad de la telemetría transmitida por la red. Esta condición puede hacer que los nombres de intervalo y los nombres de atributo generados por SDK de Azure cambien 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, añada a su aplicación los paquetes más recientes de com.azure:azure-core-tracing-opentelemetry. 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 SDK de Azure en el back-end. Sin embargo, con las llamadas asincrónicas, la correlación entre SDK de Azure y los intervalos de aplicación podrían romperse.
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 saber qué tramos y atributos emite el SDK, consulte la especificación de las convenciones semánticas del SDK de Azure. las convenciones semánticas de SDK de Azure (y OpenTelemetry) no son estables y pueden cambiar en el futuro.
Pasos siguientes
Ahora que ya conoce la funcionalidad transversal principal del SDK de Azure para Java, consulte Autenticación de Azure con Java y Azure Identity para obtener información sobre cómo crear aplicaciones seguras.