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

Článek
10/23/2023

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: rozsah a trasování. Rozsah představuje jednu operaci v trasová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 Azure Monitoru pro aplikace v Javě. 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 agenta OpenTelemetry Java, je instrumentace sady Azure SDK povolená 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 prostřednictvím přenosu, což může způsobit názvy a názvy atributů vytvořené sadou Azure SDK, které se můžou v průběhu času změnit při aktualizaci agenta. Další informace najdete v tématu Požadavky na kompatibilitu.

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 k OpenTelemetry.

Pokud chcete povolit trasování sady Azure SDK, přidejte do aplikace nejnovější 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 back-endu získat sadu Azure SDK. U asynchronních volání ale může dojít k přerušení korelace mezi sadou Azure SDK a rozsahy aplikací.

Sada Azure SDK ve výchozím nastavení používá io.opentelemetry.context.Context.current()implicitně šíření OpenTelemetry jako nadřazeného do nových rozsahů. 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 trasování

Azure SDK umožňuje explicitně předat kontext trasování prostřednictvím com.azure.core.util.Context trace-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

Pokud chcete zjistit, které rozsahy a atributy sada SDK generuje, projděte si specifikaci sémantických konvencí sady Azure SDK. Sémantické konvence sady Azure SDK (a OpenTelemetry) nejsou stabilní a v budoucnu se můžou změnit.

Další kroky

Teď, když znáte základní křížové funkce v sadě Azure SDK pro Javu, najdete v tématu Ověřování Azure pomocí Javy a Azure Identity a dozvíte se, jak můžete vytvářet zabezpečené aplikace.

Sdílet prostřednictvím