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.

Engedélyezheti a nyomkövetést Azure ügyfélkódtárakban az OpenTelemetry SDK használatával és konfigurálásával, vagy egy OpenTelemetry-kompatibilis ügynök használatával. 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éssel kapcsolatos két fő fogalom 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 TraceID nevű egyedi 16 bájtos sorozat megkülönbözteti a nyomkövetést. 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 nyomkövetés OpenTelemetry-ügynökkel

Ha a OpenTelemetry Java agentet használja, az Azure SDK instrumentálása az 1.12.0-s verziótól kezdve engedélyezve van.

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. Ez a feltétel a Azure SDK által létrehozott span nevek és attribútumnevek időbeli változását okozhatja, ha frissíti az ügynököt. 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. Az aszinkron hívások esetén azonban a Azure SDK és az alkalmazástartományok 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. Azure SDK (és 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.