Configurer le suivi avec le SDK Azure pour Java

  • Article

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 suivi dans les bibliothèques clientes Azure à l’aide du Kit de développement logiciel (SDK) OpenTelemetry ou à l’aide d’un agent compatible 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.

Suivi du Kit de développement logiciel (SDK) Azure avec l’agent Java Azure Monitor

En utilisant un agent in-process Java Azure Monitor, vous pouvez activer la surveillance de vos applications sans aucune modification du code. Pour plus d’informations, consultez Instrumentation automatique basée sur OpenTelemetry d’Azure Monitor pour les applications Java. La prise en charge du Kit de développement logiciel (SDK) Azure est activée par défaut à partir de la version 3.2 de l’agent.

Suivi des appels du Kit de développement logiciel (SDK) Azure avec l’agent OpenTelemetry

Si vous utilisez l’agent Java OpenTelemetry, l’instrumentation du Kit de développement logiciel (SDK) Azure est activée prête à l’emploi à partir de la version 1.12.0.

Pour plus d’informations sur la configuration des exportateurs, l’ajout d’instrumentation manuelle ou l’enrichissement des données de télémétrie, consultez OpenTelemetry Instrumentation pour Java.

Remarque

L’artefact de l’agent OpenTelemetry est stable, mais ne fournit pas de garanties de stabilité de télémétrie sur fil, ce qui peut entraîner des noms d’étendues et des noms d’attributs générés par le Kit de développement logiciel (SDK) Azure qui peuvent changer au fil du temps si vous mettez à jour l’agent. Pour plus d’informations, consultez la configuration requise pour la compatibilité.

Instrumenter manuellement l’application avec le Kit de développement logiciel (SDK) OpenTelemetry (préversion)

Si vous utilisez directement le Kit de développement logiciel (SDK) OpenTelemetry, veillez à configurer le SDK et l’exportateur pour le back-end de votre choix. Pour plus d’informations, consultez la documentation OpenTelemetry.

Pour activer le suivi du Kit de développement logiciel (SDK) Azure, ajoutez les packages les plus récents 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 devez obtenir des étendues du Kit de développement logiciel (SDK) Azure sur votre back-end. Toutefois, avec les appels asynchrones, la corrélation entre le KIT de développement logiciel (SDK) Azure et les étendues d’application peut être interrompue.

Par défaut, le Kit de développement logiciel (SDK) Azure utilise io.opentelemetry.context.Context.current(), propagé implicitement par OpenTelemetry, en tant que parent vers de nouvelles étendues. Dans les appels asynchrones, la propagation de contexte implicite s’interrompt. Les agents OpenTelemetry résolvent ce problème en aidant la propagation du contexte, mais le SDK OpenTelemetry n’a pas de telles fonctionnalités.

Passer explicitement le contexte de trace

Le Kit de développement logiciel (SDK) Azure permet de transmettre explicitement com.azure.core.util.Context le contexte de trace sous la trace-context clé. Lorsque vous fournissez un contexte de trace explicite, le Kit de développement logiciel (SDK) Azure l’utilise au lieu de celui implicite, ce qui permet la corrélation entre l’application et le Kit de développement logiciel (SDK) Azure.

Dans l’exemple suivant, lorsqu’une requête web entrante est tracée manuellement, la bibliothèque cliente de configuration d’application est appelée de façon asynchrone dans l’étendue 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 suivi du Kit de développement logiciel (SDK) Azure

Pour savoir quelles étendues et attributs le SDK émet, consultez la spécification des conventions sémantiques du Kit de développement logiciel (SDK) Azure. Les conventions sémantiques du Kit de développement logiciel (SDK) Azure (et OpenTelemetry) ne sont pas stables et peuvent changer à 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.