Nyomkövetés konfigurálása a Java-hoz készült Azure SDK-ban

  • Cikk

Ez a cikk áttekintést nyújt arról, hogyan konfigurálhatja az Azure SDK for Java-t a nyomkövetési funkciók integrálásához.

A nyomkövetést az Azure-ügyfélkódtárakban az OpenTelemetry SDK vagy egy OpenTelemetry-kompatibilis ügynök használatával engedélyezheti. Az OpenTelemetria egy népszerű nyílt forráskódú megfigyelhetőségi keretrendszer, amely a natív felhőbeli szoftverek telemetriai adatainak létrehozására, rögzítésére és gyűjtésére használható.

A nyomkövetésnek két fő fogalma van: a span és a trace. A span egyetlen műveletet jelöl egy nyomkövetésben. A hatókör jelenthet HTTP-kérést, távoli eljáráshívást (RPC), adatbázis-lekérdezést vagy akár a kód elérési útját is. A nyomkövetés a rendszereken keresztüli munka útvonalát ábrázoló spanok fa. A nyomkövetést önállóan is megkülönböztetheti egy egyedi, 16 bájtos sorozattal, amelyet TraceID-nek hívunk. Ezekről a fogalmakról és az OpenTelemetria kapcsolatáról az OpenTelemetry dokumentációjában talál további információt.

Azure SDK-nyomkövetés az Azure Monitor Java-ügynökkel

Az Azure Monitor Java folyamatban lévő ügynökével kódmódosítások nélkül engedélyezheti az alkalmazások monitorozását. További információ: Azure Monitor OpenTelemetry-alapú automatikus rendszerállapot Java-alkalmazásokhoz. Az Azure SDK támogatása alapértelmezés szerint engedélyezve van az ügynök 3.2-es verziójától kezdve.

Azure SDK-hívások nyomon követése az OpenTelemetry-ügynökkel

OpenTelemetry Java-ügynök használata esetén az Azure SDK-rendszerállapot az 1.12.0-s verziótól kezdve engedélyezve van.

Az exportőrök konfigurálásáról, a manuális rendszerállapot hozzáadásáról vagy a telemetriai adatok bővítéséről további információt a Java OpenTelemetry Instrumentation című témakörben talál.

Megjegyzés:

Az OpenTelemetry-ügynök összetevő stabil, de nem biztosít vezetéken túli telemetriai stabilitási garanciákat, ami az Azure SDK által létrehozott span neveket és attribútumneveket okozhatja, amelyek idővel változhatnak az ügynök frissítésekor. További információ: Kompatibilitási követelmények.

Az alkalmazás manuális beállítása OpenTelemetry SDK-val (előzetes verzió)

Ha közvetlenül OpenTelemetry SDK-t használ, mindenképpen konfigurálja az SDK-t és az exportőrt a választott háttérrendszerhez. További információt az OpenTelemetry dokumentációjában talál.

Az Azure SDK-nyomkövetés engedélyezéséhez adja hozzá a legújabb com.azure:azure-core-tracing-opentelemetry csomagokat az alkalmazáshoz. A Mavenben például adja hozzá a következő bejegyzést a pom.xml fájlhoz:

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

Ha most futtatja az alkalmazást, az Azure SDK-t a háttérrendszerre kell helyeznie. Aszinkron hívások esetén azonban az Azure SDK és az alkalmazások közötti korreláció megszakadhat.

Az Azure SDK alapértelmezés szerint az OpenTelemetry által implicit módon propagált szülőként használja io.opentelemetry.context.Context.current()az új tartományokra. Aszinkron hívások esetén implicit környezeti propagálási törések. Az OpenTelemetry-ügynökök úgy oldják meg ezt a problémát, hogy segítenek a környezet propagálásában, de az OpenTelemetry SDK nem rendelkezik ilyen képességekkel.

Nyomkövetési környezet átadása explicit módon

Az Azure SDK lehetővé teszi a nyomkövetési környezet átadását kifejezetten com.azure.core.util.Context a trace-context kulcs alatt. Ha explicit nyomkövetési környezetet ad meg, az Azure SDK azt használja az implicit helyett, ami lehetővé teszi az alkalmazás és az Azure SDK közötti korrelációt.

Az alábbi példában a bejövő webes kérések manuális nyomkövetésekor a rendszer aszinkron módon hívja meg az alkalmazáskonfigurációs ügyfélkódtárat a kérés hatókörében.

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

//...

Azure SDK-nyomkövetési konvenciók

Az SDK által kibocsátott értékek és attribútumok meghatározásához tekintse meg az Azure SDK szemantikai konvenciók specifikációját. Az Azure SDK (és Az OpenTelemetria) szemantikai konvenciók nem stabilak, és a jövőben változhatnak.

További lépések

Most, hogy már ismeri a Java Azure SDK alapvető keresztvágási funkcióit, tekintse meg a Java-val és az Azure Identity-lel való Azure-hitelesítést, és ismerje meg, hogyan hozhat létre biztonságos alkalmazásokat.