Konfigurieren von Ablaufverfolgung im Azure SDK für Java

Artikel
10/04/2024

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 gängiges Open-Source-Ablaufverfolgungsframework zum Generieren, Erfassen und Sammeln von Telemetriedaten für cloudnative Software.

Es gibt zwei grundlegende Konzepte im Zusammenhang mit Ablaufverfolgung: Spanne und Stapelüberwachung. Eine Spanne stellt einen einzelnen Vorgang in einer Stapelüberwachung 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 Stapelüberwachung 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 Monitors 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 Java-Agent „OpenTelemetry” 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 in der Kompatibilitätsanforderungen.

Manuelles Instrumentieren der Anwendung mit dem OpenTelemetry SDK (Vorschau)

Wenn Sie OpenTelemetry SDK direkt verwenden, müssen Sie das SDK und den Exporteur für das Back-End 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 wird die implizite Kontextverteilung unterbrochen. 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, finden Sie weitere Informationen zum Erstellen von sicheren Anwendungen unter Azure-Authentifizierung mit Java und Azure Identity.

Freigeben über