Configurer le suivi avec le SDK Azure pour Java

Article
10/07/2024

Cet article fournit une vue d’ensemble de la configuration du kit de développement logiciel Azure pour Java afin d’intégrer la fonctionnalité de suivi.

Vous pouvez activer le traçage dans les bibliothèques client Azure en configurant le SDK OpenTelemetry ou en utilisant un agent compatible avec OpenTelemetry. OpenTelemetry est un framework d’observabilité open source très utilisé pour la génération, la capture et la collecte des données de télémétrie pour les logiciels cloud natifs.

Il existe deux concepts clés liés au suivi : l’étendue et le suivi. L’étendue représente une opération unique dans une trace. Une étendue peut représenter une requête HTTP, un appel de procédure distante, une requête de base de données ou même le chemin qu’emprunte votre code. Une trace est une arborescence d’étendues qui montre le chemin de travail dans un système. Vous pouvez distinguer la trace grâce à une séquence unique de 16 octets appelée TraceID. Pour plus d’informations sur ces concepts et sur la façon dont ils sont liés à OpenTelemetry, consultez la documentation OpenTelemetry.

Traçage du SDK Azure avec l'agent Java d'Azure Monitor

En utilisant l'agent Java in-process d'Azure Monitor, vous pouvez activer la surveillance de vos applications sans avoir à modifier le code. Pour plus d’informations, consultez Instrumentation automatique basée sur OpenTelemetry d’Azure Monitor pour les applications Java. La compatibilité avec le SDK Azure est activée par défaut à partir de la version 3.2 de l'agent.

Tracer les appels du SDK Azure avec l'agent OpenTelemetry

Si vous utilisez l'agent Java OpenTelemetry, l'instrumentation du SDK Azure est activée dès la version 1.12.0.

Pour plus de détails sur la configuration des exportateurs, l'ajout d'une instrumentation manuelle ou l'enrichissement de la télémétrie, voir Instrumentation OpenTelemetry pour Java.

Remarque

L'artefact de l'agent OpenTelemetry est stable, mais il n'offre pas de garantie de stabilité de la télémétrie sur le fil, ce qui signifie que les noms de span et d'attributs produits par le SDK Azure peuvent changer si vous mettez à jour l'agent. Pour plus d'informations, voir Conditions de compatibilité.

Instrumenter manuellement l'application avec OpenTelemetry SDK (version preview)

Si vous utilisez directement le SDK OpenTelemetry, assurez-vous de configurer correctement le SDK ainsi que l'exportateur pour le backend de votre choix. Pour plus d'informations, consultez la documentation OpenTelemetry.

Pour activer le traçage du SDK Azure, ajoutez les derniers packages com.azure:azure-core-tracing-opentelemetry à votre application. Par exemple, dans Maven, ajoutez l'entrée suivante à votre fichier pom.xml :

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

Si vous exécutez l'application maintenant, vous devriez observer des spans SDK Azure sur votre backend. Cependant, lors des appels asynchrones, la corrélation entre le SDK Azure et les spans de l'application peut être rompue.

Par défaut, Azure SDK utilise io.opentelemetry.context.Context.current(), implicitement propagé par OpenTelemetry, comme parent pour les nouvelles portées. Dans les appels asynchrones, la propagation implicite du contexte est interrompue. Les agents OpenTelemetry résolvent ce problème en facilitant la propagation du contexte, mais le SDK OpenTelemetry n'a pas encore de telles capacités.

Transmettre explicitement le contexte de traçage

Azure SDK permet de passer explicitement le contexte de la trace par le biais de com.azure.core.util.Context sous la clé trace-context. Lorsque vous transmettez un contexte de traçage explicite, le SDK Azure l'utilise à la place du contexte implicite, assurant ainsi une corrélation entre l'application et les spans du SDK Azure.

Dans l'exemple suivant, une requête Web entrante est tracée manuellement, et la bibliothèque client de configuration d'application est appelée de manière asynchrone dans la portée de cette requête.

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

//...

Conventions de traçage du SDK Azure

Pour connaître les portées et les attributs émis par le SDK, consultez la section Spécification des conventions sémantiques du SDK d'Azure. Les conventions sémantiques du SDK Azure (et d'OpenTelemetry) ne sont pas stables et pourraient évoluer à l'avenir.

Étapes suivantes

Maintenant que vous connaissez les principales fonctionnalités du SDK Azure pour Java, consultez Authentification Azure avec Java et Azure Identity pour savoir comment créer des applications sécurisées.

Partager via