Konfigurera spårning i Azure SDK för Java

  • Artikel

Den här artikeln innehåller en översikt över hur du konfigurerar Azure SDK 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 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.

Det finns två viktiga begrepp som rör spårning: span och spårning. 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. Du kan särskilja en spårning på egen hand med en unik 16-bytessekvens som kallas traceID. Mer information om dessa begrepp och hur de relaterar till OpenTelemetry finns i dokumentationen om OpenTelemetry.

Azure SDK-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. Mer information finns i Azure Monitor OpenTelemetry-baserad automatisk instrumentering för Java-program. Azure SDK-stöd är aktiverat som standard från och med agentversion 3.2.

Spåra Azure SDK-anrop med OpenTelemetry-agenten

Om du använder OpenTelemetry Java-agenten aktiveras Azure SDK-instrumentation direkt 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.

Kommentar

OpenTelemetry-agentartefakten är stabil, men ger inga garantier för telemetristabilitet över kabel, vilket kan orsaka spannamn och attributnamn som produceras av Azure SDK som kan ändras över tid om du uppdaterar agenten. Mer information finns i Kompatibilitetskrav.

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 valfri serverdel. Mer information finns i Dokumentation om OpenTelemetry.

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

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

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

Som standard använder io.opentelemetry.context.Context.current()Azure SDK , implicit spridd av OpenTelemetry, som överordnad till nya intervall. 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 SDK kan du uttryckligen skicka spårningskontexten trace-context under com.azure.core.util.Context nyckeln. När du anger explicit spårningskontext använder Azure SDK den i stället för den implicita, vilket möjliggör korrelation mellan program- och Azure SDK-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 SDK-spårningskonventioner

Information om vilka intervall och attribut som SDK:et genererar finns i specifikationen för Semantiska Azure SDK-konventioner. Semantiska Azure SDK-konventioner (och OpenTelemetry) är inte stabila och kan ändras i framtiden.

Nästa steg

Nu när du är bekant med de grundläggande övergripande funktionerna i Azure SDK för Java kan du läsa Azure-autentisering med Java och Azure Identity för att lära dig hur du kan skapa säkra program.