Konfigurieren von Ablaufverfolgung im Azure SDK für Java

Dieser Artikel bietet eine Übersicht, wie Sie das Azure SDK für Java konfigurieren, um Ablaufverfolgungsfunktionalität zu integrieren.

Sie können die Ablaufverfolgung in Azure-Clientbibliotheken aktivieren, indem Sie das OpenTelemetry SDK oder einen mit OpenTelemetry kompatiblen Agent konfigurieren. OpenTelemetry ist ein beliebtes Open-Source-Observability-Framework zum Generieren, Erfassen und Sammeln von Telemetriedaten für cloud-native Software.

Es gibt zwei grundlegende Konzepte im Zusammenhang mit Ablaufverfolgung: Spanne und Stapelüberwachung. Ein Abschnitt stellt einen einzelnen Vorgang in einer Spur dar. Eine Spanne kann eine HTTP-Anforderung, einen Remoteprozeduraufruf (RPC), eine Datenbankabfrage oder sogar den Pfad darstellen, den Ihr Code annimmt. Bei einer Stapelüberwachung handelt es sich um eine Struktur von Spannen, die den Arbeitspfad durch ein System zeigt. Sie können eine Spur für sich allein durch eine eindeutige 16-Byte-Sequenz, die als TraceID bezeichnet wird, unterscheiden. Weitere Informationen zu diesen Konzepten und ihrer Beziehung zu OpenTelemetry finden Sie in der OpenTelemetry-Dokumentation.

Azure SDK-Ablaufverfolgung mit Azure Monitor Java-Agent

Durch die Verwendung eines Azure Monitor Java In-Process-Agenten können Sie die Überwachung Ihrer Anwendungen ohne Codeänderungen aktivieren. Weitere Informationen finden Sie unter Azure Monitor OpenTelemetry-basierte automatische Instrumentierung für Java-Anwendungen. Die Azure SDK-Unterstützung ist standardmäßig aktiviert, beginnend mit Agent Version 3.2.

Nachverfolgen von Azure SDK-Aufrufen mit dem OpenTelemetry-Agent

Wenn Sie den OpenTelemetry Java agent verwenden, ist die Azure SDK-Instrumentierung ab Version 1.12.0 sofort aktiviert.

Weitere Informationen zum Konfigurieren von Exporteuren, zum Hinzufügen manueller Instrumentierung oder zum Anreichern von Telemetrie finden Sie unter OpenTelemetry Instrumentation für Java.

Hinweis

Das Artefakt des OpenTelemetry-Agenten ist stabil, bietet jedoch keine Over-the-Wire-Stabilitätsgarantie für die Telemetrie, was dazu führen kann, dass sich die vom Azure SDK erzeugten Spannen- und Attributnamen im Laufe der Zeit ändern können, wenn Sie den Agenten aktualisieren. Weitere Informationen finden Sie unter Kompatibilitätsanforderungen.

Manuelles Instrumentieren der Anwendung mit dem OpenTelemetry SDK (Vorschau)

Wenn Sie das OpenTelemetry SDK direkt verwenden, stellen Sie sicher, dass Sie das SDK und den Exporteur für das Backend Ihrer Wahl konfigurieren. Weitere Informationen finden Sie in der OpenTelemetry-Dokumentation.

Um die Azure SDK-Ablaufverfolgung zu aktivieren, fügen Sie Ihrer Anwendung die neuesten com.azure:azure-core-tracing-opentelemetry Pakete hinzu. Fügen Sie beispielsweise in Maven den folgenden Eintrag pom.xml zu Ihrer Datei hinzu:

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

Wenn Sie die Anwendung jetzt ausführen, sollten Sie Azure SDK-Spans in Ihrem Back-End erhalten. Bei asynchronen Aufrufen kann jedoch die Korrelation zwischen Azure SDK und Anwendungsspannen unterbrochen werden.

Standardmäßig verwendet Azure SDK io.opentelemetry.context.Context.current(), das implizit von OpenTelemetry verbreitet wird, als übergeordnetes Element für neue Spans. Bei asynchronen Aufrufen geht die implizite Kontextweitergabe verloren. OpenTelemetry-Agents lösen dieses Problem, indem sie die Kontextverteilung unterstützen, aber das OpenTelemetry SDK verfügt nicht über solche Funktionen.

Expliziten Ablaufverfolgungskontext übergeben

Das Azure SDK ermöglicht das explizite Übergeben des Ablaufverfolgungskontexts durch com.azure.core.util.Context unter dem trace-context Schlüssel. Wenn Sie expliziten Ablaufverfolgungskontext bereitstellen, verwendet Azure SDK diesen anstelle des impliziten Kontexts, der die Korrelation zwischen Anwendung und Azure SDK-Spans ermöglicht.

Im folgenden Beispiel wird die Anwendungskonfigurations-Clientbibliothek asynchron im Bereich dieser Anforderung aufgerufen, wenn eine eingehende Webanforderung manuell nachverfolgt wird.

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

//...

Konventionen für die Ablaufverfolgung von Azure SDK

Informationen dazu, welche Bereiche und Attribute das SDK emittiert, finden Sie in der Spezifikation der Azure SDK-Semantikkonventionen. Die Semantikkonventionen von Azure SDK (und OpenTelemetry) sind nicht stabil und können sich in Zukunft ändern.

Nächste Schritte

Da Sie nun mit den übergreifenden Kernfunktionen des Azure SDK für Java vertraut sind, sehen Sie sich Azure-Authentifizierung mit Java und Azure Identity an, um zu lernen, wie Sie sichere Anwendungen erstellen können.