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

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önyvtá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 nyom egy span-fa, amely a rendszeren keresztüli munka útvonalát mutatja. 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ókért lásd: Azure Monitor OpenTelemetry-alapú automatikus eszköz-besorolás 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

Ha az OpenTelemetry Java ügynököt használja, az Azure SDK-instrumentáció alapértelmezetten engedélyezett az 1.12.0-s verziótól kezdve.

További részletekért arról, hogyan konfigurálhatók az exportőrök, adható hozzá manuális műszerelés, vagy bővíthető a telemetria, tekintse meg a Java OpenTelemetry Instrumentation-t.

Feljegyzé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ókért lásd a Kompatibilitási követelmények részt.

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 io.opentelemetry.context.Context.current()-et használja szülőként az új spanekhez. Aszinkron hívások esetén az implicit környezeti kontextus terjesztése megszakad. 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.

Az nyomkövetési környezetet egyértelműen adja át

Az Azure SDK lehetővé teszi a nyomkövetési környezet kifejezett átadását a com.azure.core.util.Context kontextusban 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 spanok é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.

Következő lépések

Most, hogy már ismeri a Java Azure SDK alapvető átfogó funkcióit, tekintse meg a Java és az Azure Identity használatával történő Azure-hitelesítést, és ismerje meg, hogyan hozhat létre biztonságos alkalmazásokat.