Tracering configureren in de Azure SDK voor Java

Dit artikel bevat een overzicht van het configureren van de Azure SDK voor Java om traceringsfunctionaliteit te integreren.

U kunt tracering inSchakelen in Azure-clientbibliotheken door de OpenTelemetry SDK te gebruiken en te configureren of door een met OpenTelemetry compatibele agent te gebruiken. OpenTelemetry is een populair opensource-waarneembaarheidsframework voor het genereren, vastleggen en verzamelen van telemetriegegevens voor cloudeigen software.

Er zijn twee belangrijke concepten met betrekking tot tracering: span en trace. Een span vertegenwoordigt één bewerking in een tracering. Een bereik kan een HTTP-aanvraag, een externe procedureaanroep (RPC), een databasequery of zelfs het pad vertegenwoordigen dat uw code gebruikt. Een tracering is een structuur van spanten die het pad van het werk door een systeem laten zien. U kunt een tracering op zichzelf onderscheiden door een unieke reeks van 16 bytes die een TraceID wordt genoemd. Zie de Documentatie voor OpenTelemetry voor meer informatie over deze concepten en hoe deze betrekking hebben op OpenTelemetry.

Azure SDK-tracering met Azure Monitor Java-agent

Met behulp van een Java-in-process agent van Azure Monitor kunt u bewaking van uw toepassingen inschakelen zonder codewijzigingen. Zie automatische instrumentatie op basis van Azure Monitor OpenTelemetry voor Java-toepassingen voor meer informatie. Azure SDK-ondersteuning is standaard ingeschakeld vanaf agentversie 3.2.

Azure SDK-aanroepen traceren met OpenTelemetry-agent

Als u de OpenTelemetry Java-agent gebruikt, wordt out-of-the-box-instrumentatie van Azure SDK ingeschakeld vanaf versie 1.12.0.

Zie OpenTelemetry Instrumentation voor Java voor meer informatie over het configureren van exporteurs, het toevoegen van handmatige instrumentatie of het verrijken van telemetrie.

Notitie

OpenTelemetry-agentartefact is stabiel, maar biedt geen garanties voor over-the-wire telemetriestabiliteit, wat kan leiden tot spannamen en kenmerknamen die worden geproduceerd door Azure SDK, die na verloop van tijd kunnen veranderen als u de agent bijwerkt. Zie Compatibiliteitsvereisten voor meer informatie.

De toepassing handmatig instrumenteren met OpenTelemetry SDK (preview)

Als u OpenTelemetry SDK rechtstreeks gebruikt, moet u de SDK en exporteur configureren voor de back-end van uw keuze. Zie de OpenTelemetry-documentatie voor meer informatie.

Als u Tracering van Azure SDK wilt inschakelen, voegt u de nieuwste com.azure:azure-core-tracing-opentelemetry pakketten toe aan uw toepassing. Voeg bijvoorbeeld in Maven de volgende vermelding toe aan uw pom.xml-bestand :

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

Als u de toepassing nu uitvoert, moet u Azure SDK-spans op uw back-end ophalen. Bij asynchrone aanroepen kan de correlatie tussen De Azure SDK en de toepassingsspanne echter worden verbroken.

Azure SDK maakt io.opentelemetry.context.Context.current()standaard gebruik van , impliciet doorGegeven door OpenTelemetry, als bovenliggend element aan nieuwe bereiken. In asynchrone aanroepen worden impliciete contextdoorgifte-einden gebruikt. OpenTelemetry-agents lossen dit probleem op door contextdoorgifte te helpen, maar de OpenTelemetry SDK beschikt niet over dergelijke mogelijkheden.

Traceringscontext expliciet doorgeven

Met Azure SDK kan traceringscontext expliciet worden doorgegeven onder com.azure.core.util.Context de trace-context sleutel. Wanneer u een expliciete traceringscontext opgeeft, gebruikt Azure SDK deze in plaats van de impliciete context, waardoor correlatie tussen de toepassing en De Azure SDK mogelijk is.

In het volgende voorbeeld wordt de toepassingsconfiguratieclientbibliotheek asynchroon aangeroepen in het bereik van deze aanvraag wanneer een binnenkomende webaanvraag handmatig wordt getraceerd.

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

//...

Azure SDK-traceringsconventies

Zie de specificatie van de semantische conventies van De Azure SDK om erachter te komen welke diagrammen en kenmerken de SDK verzendt. Semantische conventies van Azure SDK (en OpenTelemetry) zijn niet stabiel en kunnen in de toekomst veranderen.

Volgende stappen

Nu u bekend bent met de belangrijkste cross-cutting functionaliteit in de Azure SDK voor Java, raadpleegt u Azure-verificatie met Java en Azure Identity om te leren hoe u veilige toepassingen kunt maken.