Konfigurace trasování v sadě Azure SDK pro Javu

Tento článek obsahuje přehled konfigurace sady Azure SDK pro Javu pro integraci funkcí trasování.

Trasování můžete povolit v klientských knihovnách Azure pomocí a konfiguraci sady OpenTelemetry SDK nebo pomocí agenta kompatibilního s OpenTelemetry. OpenTelemetry je oblíbená opensourcová architektura pozorovatelnosti pro generování, zachytávání a shromažďování telemetrických dat pro software nativní pro cloud.

Existují dva klíčové koncepty související s trasováním: span a trasování. Úsek představuje jednu operaci ve sledování. Rozsah může představovat požadavek HTTP, vzdálené volání procedur (RPC), databázový dotaz nebo dokonce cestu, kterou váš kód přebírá. Trasování je strom rozpětí zobrazující cestu práce v systému. Trasování můžete odlišit samostatně pomocí jedinečné sekvence 16 bajtů, která se nazývá TraceID. Další informace o těchto konceptech a o tom, jak souvisí s OpenTelemetry, najdete v dokumentaci k OpenTelemetry.

Trasování sady Azure SDK s využitím agenta Java služby Azure Monitor

Pomocí agenta v procesu v Javě služby Azure Monitor můžete povolit monitorování aplikací bez jakýchkoli změn kódu. Další informace najdete v tématu Automatická instrumentace založená na technologii OpenTelemetry v Azure Monitoru pro Java aplikace. Podpora sady Azure SDK je ve výchozím nastavení povolená od agenta verze 3.2.

Trasování volání sady Azure SDK pomocí agenta OpenTelemetry

Pokud používáte OpenTelemetry Java agenta, je instrumentace Azure SDK povolena již od verze 1.12.0.

Další podrobnosti o konfiguraci exportérů, přidání ruční instrumentace nebo obohacení telemetrie najdete v tématu OpenTelemetry Instrumentation for Java.

Poznámka:

Artefakt agenta OpenTelemetry je stabilní, ale neposkytuje záruky stability telemetrie při přenosu dat, což může způsobit, že názvy rozpětí a názvy atributů vytvořené knihovnou Azure SDK se mohou změnit v průběhu času, pokud aktualizujete agenta. Další informace najdete v části Kompatibilní požadavky.

Ruční instrumentace aplikace pomocí sady OpenTelemetry SDK (Preview)

Pokud používáte sadu OpenTelemetry SDK přímo, nezapomeňte nakonfigurovat sadu SDK a exportér pro back-end podle vašeho výběru. Další informace najdete v dokumentaci OpenTelemetry.

Pokud chcete povolit trasování sady Azure SDK, přidejte do aplikace aktuální com.azure:azure-core-tracing-opentelemetry balíčky. Například v Mavenu přidejte do souboru pom.xml následující položku:

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

Pokud teď aplikaci spustíte, měli byste na backendu získat segmenty Azure SDK. U asynchronních volání ale může dojít k přerušení korelace mezi sadou Azure SDK a rozsahy aplikací.

Ve výchozím nastavení Azure SDK používá io.opentelemetry.context.Context.current() implicitně propagovaný OpenTelemetry, který slouží jako nadřazený prvek pro nové úseky. V asynchronních voláních se implicitní šíření kontextu přeruší. Agenti OpenTelemetry tento problém řeší tím, že pomáhají rozšířit kontext, ale sada OpenTelemetry SDK takové funkce nemá.

Explicitně předat kontext sledování

Azure SDK umožňuje explicitně předat kontext trasování prostřednictvím com.azure.core.util.Contexttrace-context klíče. Když zadáte explicitní kontext trasování, sada Azure SDK ho použije místo implicitního kontextu, což umožňuje korelaci mezi aplikací a sadou Azure SDK.

V následujícím příkladu se při ručním trasování příchozího webového požadavku volá klientská knihovna konfigurace aplikace asynchronně v oboru tohoto požadavku.

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

//...

Konvence trasování sady Azure SDK

Abyste zjistili, které rozsahy a atributy SDK emituje, podívejte se na specifikaci sémantických konvencí Azure SDK. Sémantické konvence sady Azure SDK (a OpenTelemetry) nejsou stabilní a v budoucnu se můžou změnit.

Další kroky

Teď, když jste obeznámeni se základní průřezovou funkcionalitou v sadě Azure SDK pro Javu, podívejte se na Ověřování Azure pomocí Javy a Azure Identity, kde zjistíte, jak můžete vytvářet zabezpečené aplikace.