Konfigurera spårning i Azure SDKs för Java

Den här artikeln innehåller en översikt över hur du konfigurerar Azure SDKs för Java för att integrera spårningsfunktioner.

Du kan aktivera spårning i Azure klientbibliotek med hjälp av och konfigurera OpenTelemetry SDK eller med hjälp av en OpenTelemetry-kompatibel agent. OpenTelemetry är ett populärt ramverk för observerbarhet med öppen källkod för att generera, samla in och samla in telemetridata för molnbaserad programvara.

Två viktiga begrepp som rör spårning är span och trace. Ett spann representerar en enskild åtgärd i en spårning. Ett intervall kan representera en HTTP-begäran, ett fjärrproceduranrop (RPC), en databasfråga eller till och med den sökväg som koden tar. En spårning är ett träd med intervall som visar arbetsvägen genom ett system. En unik 16-bytessekvens som kallas traceID särskiljer en spårning. För mer information om dessa begrepp och hur de relaterar till OpenTelemetry, se OpenTelemetry-dokumentationen.

Azure SDKs-spårning med Azure Monitor Java-agent

Genom att använda en Azure Monitor Java-processagent kan du aktivera övervakning av dina program utan några kodändringar. För mer information, se Azure Monitor OpenTelemetry-baserad automatisk instrumentering för Java-program. Azure SDKs-stöd är aktiverat som standard från och med agentversion 3.2.

Azure SDKs spårning med OpenTelemetry-agenten

Om du använder OpenTelemetry Java agent aktiveras Azure SDKs instrumentation från version 1.12.0.

Mer information om hur du konfigurerar exportörer, lägger till manuell instrumentering eller berikar telemetri finns i OpenTelemetry Instrumentation för Java.

Instrumentera programmet manuellt med OpenTelemetry SDK (förhandsversion)

Om du använder OpenTelemetry SDK direkt måste du konfigurera SDK och exportör för den serverdel du väljer. För mer information, se OpenTelemetry-dokumentationen.

Om du vill aktivera Azure SDKs-spårning lägger du till de senaste com.azure:azure-core-tracing-opentelemetry paketen i ditt program. Lägg till exempel i Maven följande post i din pom.xml-fil :

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

Om du kör programmet nu bör du få Azure SDKs-intervall på serverdelen. Men med asynkrona anrop kan korrelationen mellan Azure SDKs och programintervall vara bruten.

Som standard använder Azure SDKs io.opentelemetry.context.Context.current(), implicit spridd av OpenTelemetry, som en förälder till nya spans. I asynkrona anrop bryter implicit kontextspridning. OpenTelemetry-agenter löser det här problemet genom att hjälpa kontextspridning, men OpenTelemetry SDK har inte sådana funktioner.

Skicka spårningskontext explicit

Med Azure SDKs kan du uttryckligen skicka spårningskontexten "trace-context" genom "com.azure.core.util.Context"-nyckeln. När du anger explicit spårningskontext använder Azure SDKs den i stället för den implicita, vilket möjliggör korrelation mellan program- och Azure SDKs-intervall.

I följande exempel, när en inkommande webbbegäran spåras manuellt, anropas klientbiblioteket för programkonfiguration asynkront i omfånget för den här begäran.

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 SDKs-spårningskonventioner

För att ta reda på vilka spannar och attribut som SDK:et emitterar, se Azure SDKs:s semantiska konventionsspecifikation. Azure SDKs (och OpenTelemetry) semantiska konventioner är inte stabila och kan ändras i framtiden.

Nästa steg

Nu när du är bekant med de centrala tvärgående funktionerna i Azure SDKs för Java, se Azure-autentisering med Java och Azure Identity för att lära dig hur du kan skapa säkra program.