Skonfiguruj śledzenie w 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 segmentów pokazującym przepływ pracy przez system. Ślad można odróżnić dzięki unikatowej 16-bajtowej sekwencji zwanej TraceID. Aby uzyskać więcej informacji na temat tych pojęć i sposobu ich powiązania z usługą OpenTelemetry, zobacz dokumentację platformy OpenTelemetry.

Śledzenie Azure SDK za pomocą agenta Java w usłudze 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 automatyczna instrumentacja oparta na OpenTelemetry 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 OpenTelemetry dla Javy, instrumentacja zestawu Azure SDK jest automatycznie włączana od 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 / Notatka

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 przez ciebie docelowego zaplecza. Aby uzyskać więcej informacji, zobacz dokumentację platformy OpenTelemetry.

Aby włączyć śledzenie 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 Azure SDK używa io.opentelemetry.context.Context.current(), który jest niejawnie propagowany przez bibliotekę OpenTelemetry, jako nadrzędny dla nowych spanów. W wywołaniach asynchronicznych przerywa się niejawna propagacja kontekstu. Agenci OpenTelemetry rozwiązali ten problem, pomagając propagować kontekst, ale zestaw SDK OpenTelemetry nie ma takich możliwości.

Przekazywanie kontekstu śledzenia w sposób jawny

Azure SDK umożliwia jawne przekazywanie kontekstu śledzenia za pomocą com.azure.core.util.Context pod kluczem trace-context. Po podaniu jawnego kontekstu śledzenia Azure SDK używa go zamiast niejawnego, co umożliwia korelację między aplikacją a 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 narzędzi 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.

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