Konfigurowanie śledzenia w zestawie Azure SDK dla języka Java

Ten artykuł zawiera omówienie sposobu konfigurowania zestawu Azure SDK dla języka Java w celu zintegrowania funkcji śledzenia.

Śledzenie w bibliotekach klienckich platformy Azure można włączyć przy użyciu zestawu SDK openTelemetry lub przy użyciu agenta zgodnego z biblioteką OpenTelemetry. OpenTelemetry to popularna platforma do obserwacji typu open source do generowania, przechwytywania i zbierania danych telemetrycznych dla oprogramowania natywnego dla chmury.

Istnieją dwa kluczowe pojęcia związane z śledzeniem: span i trace. Zakres reprezentuje jedną operację w śladach. Zakres może reprezentować żądanie HTTP, zdalne wywołanie procedury (RPC), zapytanie bazy danych, a nawet ścieżkę, którą przyjmuje kod. Ślad jest drzewem rozpiętości pokazującym ścieżkę pracy przez system. Ślad można odróżnić samodzielnie od unikatowej sekwencji 16 bajtów o nazwie TraceID. Aby uzyskać więcej informacji na temat tych pojęć i sposobu ich powiązania z usługą OpenTelemetry, zobacz dokumentację platformy OpenTelemetry.

Śledzenie zestawu Azure SDK za pomocą agenta Java usługi Azure Monitor

Za pomocą agenta przetwarzania java usługi Azure Monitor można włączyć monitorowanie aplikacji bez żadnych zmian w kodzie. Aby uzyskać więcej informacji, zobacz Azure Monitor OpenTelemetry oparte na automatycznej instrumentacji dla aplikacji Java. Obsługa zestawu Azure SDK jest domyślnie włączona, począwszy od agenta w wersji 3.2.

Śledzenie wywołań zestawu Azure SDK za pomocą agenta OpenTelemetry

Jeśli używasz agenta Języka Java openTelemetry, instrumentacja zestawu Azure SDK jest włączona w wersji 1.12.0.

Aby uzyskać więcej informacji na temat konfigurowania eksporterów, dodawania instrumentacji ręcznej lub wzbogacania telemetrii, zobacz Instrumentacja OpenTelemetry dla języka Java.

Uwaga

Artefakt agenta OpenTelemetry jest stabilny, ale nie zapewnia gwarancji stabilności telemetrii za pośrednictwem przewodu, co może spowodować, że nazwy zakresu i nazwy atrybutów generowane przez zestaw Azure SDK mogą ulec zmianie w czasie w przypadku zaktualizowania agenta. Aby uzyskać więcej informacji, zobacz Wymagania dotyczące zgodności.

Ręczne instrumentowanie aplikacji przy użyciu zestawu OpenTelemetry SDK (wersja zapoznawcza)

Jeśli bezpośrednio używasz zestawu Sdk OpenTelemetry, skonfiguruj zestaw SDK i eksportera dla wybranego zaplecza. Aby uzyskać więcej informacji, zobacz dokumentację platformy OpenTelemetry.

Aby włączyć śledzenie zestawu Azure SDK, dodaj najnowsze com.azure:azure-core-tracing-opentelemetry pakiety do aplikacji. Na przykład w narzędziu Maven dodaj następujący wpis do pliku pom.xml :

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

Jeśli teraz uruchomisz aplikację, należy pobrać zakresy zestawu Azure SDK na zapleczu. Jednak w przypadku wywołań asynchronicznych korelacja między zestawem Azure SDK i zakresami aplikacji może zostać przerwana.

Domyślnie zestaw Azure SDK używa io.opentelemetry.context.Context.current()elementu niejawnie propagowanego przez bibliotekę OpenTelemetry jako elementu nadrzędnego do nowych zakresów. W wywołaniach asynchronicznych niejawne podziały propagacji kontekstu. Agenci OpenTelemetry rozwiązali ten problem, pomagając propagować kontekst, ale zestaw SDK OpenTelemetry nie ma takich możliwości.

Jawne przekazywanie kontekstu śledzenia

Zestaw Azure SDK umożliwia jawne przekazywanie kontekstu śledzenia za trace-context pomocą com.azure.core.util.Context klucza. Po podaniu jawnego kontekstu śledzenia zestaw Azure SDK używa go zamiast niejawnego, co umożliwia korelację między aplikacją a zestawem Azure SDK.

W poniższym przykładzie, gdy przychodzące żądanie internetowe jest śledzone ręcznie, biblioteka klienta konfiguracji aplikacji jest wywoływana asynchronicznie w zakresie tego żądania.

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

//...

Konwencje śledzenia zestawu Azure SDK

Aby dowiedzieć się, które zakresy i atrybuty emituje zestaw SDK, zobacz specyfikację semantycznych konwencji zestawu SDK platformy Azure. Konwencje semantyczne zestawu Azure SDK (i OpenTelemetry) nie są stabilne i mogą ulec zmianie w przyszłości.

Następne kroki

Teraz, gdy znasz podstawowe funkcje krzyżowe w zestawie Azure SDK dla języka Java, zobacz Uwierzytelnianie platformy Azure za pomocą języka Java i tożsamości platformy Azure, aby dowiedzieć się, jak tworzyć bezpieczne aplikacje.