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

Mithilfe eines In-Process-Agents für Azure Monitor-Java 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 Exportern, zum Hinzufügen manueller Instrumentierung oder zum Anreichern von Telemetrie finden Sie unter OpenTelemetry Instrumentation for Java.

Hinweis

Das OpenTelemetry-Agentartefakt ist stabil, bietet jedoch keine Stabilitätsgarantien für die Überleitungstelemetrie, was zu Spannamen und Attributnamen führen kann, die sich im Laufe der Zeit ändern können, wenn Sie den Agent aktualisieren. Weitere Informationen finden Sie unter Kompatibilitätsanforderungen.

Manuelles Instrumentieren der Anwendung mit dem OpenTelemetry SDK (Vorschau)

Wenn Sie openTelemetry SDK direkt verwenden, müssen Sie das SDK und den Exporter 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 zur Datei "pom.xml " hinzu:

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

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

Standardmäßig verwendet io.opentelemetry.context.Context.current()Das Azure SDK implizit von OpenTelemetry als übergeordnetes Element zu neuen Spans weitergegeben. 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 com.azure.core.util.Context Übergeben des Ablaufverfolgungskontexts 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 Anwendungskonfigurationsclientbibliothek 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.