Megosztás a következőn keresztül:

.NET megfigyelhetőség OpenTelemetria használatával

  • Cikk

Egy alkalmazás futtatásakor tudni szeretné, hogy az alkalmazás milyen jól teljesít, és hogy észlelje a lehetséges problémákat, mielőtt nagyobbakká válnak. Ezt úgy teheti meg, hogy telemetriai adatokat, például naplókat vagy metrikákat bocsát ki az alkalmazásból, majd figyeli és elemzi az adatokat.

Mi az a megfigyelhetőség?

Az elosztott rendszer kontextusában megfigyelhető az egyes összetevők állapotával kapcsolatos telemetriai adatok figyelése és elemzése, a teljesítmény változásainak megfigyelése és a változások okának diagnosztizálása. Ellentétben a hibakereséssel, amely invazív, és hatással lehet az alkalmazás működésére, a megfigyelhetőség célja, hogy átlátható legyen az elsődleges művelet számára, és elég kis teljesítménybeli hatással legyen ahhoz, hogy folyamatosan használható legyen.

A megfigyelhetőség általában a következők kombinációjával történik:

  • Naplók, amelyek egyedi műveleteket rögzítenek, például egy bejövő kérést, egy adott összetevő hibáját vagy egy rendelést.
  • Mérőszámok, amelyek számlálókat és mérőműszereket mérnek, például a befejezett kérelmek számát, az aktív kérelmeket, az értékesített widgeteket, vagy a kérés késésének hisztogramját.
  • Elosztott nyomkövetés, amely nyomon követi a kérelmeket és tevékenységeket az elosztott rendszer összetevői között, így láthatja az időt, és nyomon követheti az adott hibákat.

A naplók, a metrikák és az elosztott nyomkövetés együttesen a megfigyelhetőség három alappilléreként is ismertek.

Az egyes pillérek tartalmazhatnak telemetriaadatokat a következőkből:

  • A .NET-futtatókörnyezet, például a szemétgyűjtő vagy a JIT-fordító.
  • Kódtárak, például a Kestrelből (a ASP.NET webkiszolgálóról) és HttpClienta .
  • A kód által kibocsátott alkalmazásspecifikus telemetria.

Megfigyelhetőségi megközelítések a .NET-ben

A .NET-alkalmazásokban többféleképpen is elérhető a megfigyelhetőség:

  • Explicit módon kódban, hivatkozással és egy olyan kódtár használatával, mint az OpenTelemetry. Ha rendelkezik hozzáféréssel a forráskódhoz, és újra tudja építeni az alkalmazást, akkor ez a leghatékonyabb és legkonfigurálhatóbb mechanizmus.
  • Folyamaton kívüli az EventPipe használatával. Az olyan eszközök, mint a dotnet-monitor , figyelhetik a naplókat és a metrikákat, majd anélkül dolgozhatják fel őket, hogy bármilyen kód érintené őket.
  • Egy indítóhorog használatával szerelvényeket lehet injektálni a folyamatba, amely aztán összegyűjti a rendszerezést. Erre a megközelítésre példa az OpenTelemetry .NET Automatic Instrumentation.

Mi az OpenTelemetria?

Az OpenTelemetria (OTel) platformfüggetlen, nyílt szabvány a telemetriai adatok gyűjtésére és kibocsátására. Az OpenTelemetria a következőket tartalmazza:

  • API-k a kód futtatásakor a telemetriai adatok rögzítésére használható kódtárakhoz.
  • Az alkalmazásfejlesztők által használt API-k konfigurálják, hogy a rögzített adatok mely részét küldik el a hálózaton, hová küldik, és hogyan szűrhetik, pufferelhetik, bővíthetik és alakíthatják át őket.
  • A szemantikai konvenciók útmutatást nyújtanak a telemetriai adatok elnevezéséhez és tartalmához. Fontos, hogy a telemetriai adatokat előállító alkalmazások és az adatokat fogadó eszközök megegyezhessenek abban, hogy milyen típusú adatok és milyen típusú adatok hasznosak, hogy az eszközök hatékony elemzést tudjanak nyújtani.
  • Interfész az exportőrök számára. Az exportőrök olyan beépülő modulok, amelyek lehetővé teszik a telemetriai adatok meghatározott formátumban történő továbbítását különböző telemetriai háttérrendszerekbe.
  • Az OTLP-vezetékes protokoll egy szállítói semleges hálózati protokoll lehetőség a telemetriai adatok továbbításához. Egyes eszközök és szállítók ezt a protokollt a már meglévő védett protokollok mellett támogatják.

Az OTel használata számos APM-rendszer használatát teszi lehetővé, beleértve a nyílt forráskódú rendszereket, például a Prometheus és a Grafana, az Azure Monitor – a Microsoft APM-terméke az Azure-ban, vagy az OpenTelemetryvel partneri kapcsolatban álló számos APM-gyártótól .

A legtöbb nyelvhez és platformhoz vannak OpenTelemetry implementációk, beleértve a .NET-et is.

Az OpenTelemetria .NET-implementálása

A .NET OpenTelemetry implementációja kissé eltér a többi platformtól, mivel a .NET naplózást, metrikákat és tevékenység API-kat biztosít a keretrendszerben. Ez azt jelenti, hogy az OTel-nek nem kell API-kat biztosítania a kódtár-szerzők számára. A .NET OTel implementáció az alábbi platform API-kat használja a rendszerezéshez:

.NET OTel-architektúra

Az OTel az, hogy telemetriát gyűjt ezekből az API-kból és más forrásokból (a rendszerállapot-kódtárakon keresztül), majd exportálja őket egy alkalmazásteljesítmény-monitorozási (APM) rendszerbe tárolás és elemzés céljából. Az OTel iparági szabványként nyújtott előnye a telemetriai adatok gyűjtésének, általános sémáinak és szemantikájának, valamint az API-nak az az előnye, hogy az API-k hogyan integrálhatók az OTellel. Az OTel használata azt jelenti, hogy az alkalmazásoknak nem kell APM-specifikus API-kat vagy adatstruktúrákat használniuk; az OTel szabvány ellen dolgoznak. Az APM-k implementálhatnak egy APM-specifikus exportőr-összetevőt, vagy használhatják az OTLP-t, amely egy új vezetékes szabvány a telemetriai adatok APM-rendszerekbe való exportálásához.

OpenTelemetry-csomagok

Az OpenTelemetry a .NET-ben nuGet-csomagok sorozataként van implementálva, amelyek több kategóriát alkotnak:

  • Core API
  • Instrumentation – ezek a csomagok rendszerezést gyűjtenek a futtatókörnyezetből és a gyakori kódtárakból.
  • Exportőrök – ezek az APM-rendszerek, például a Prometheus, a Jaeger és az OTLP felületei.

Az alábbi táblázat a fő csomagokat ismerteti.

Csomag neve Leírás
OpenTelemetria Az OTEL alapvető funkcióit biztosító fő kódtár
OpenTelemetry.Instrumentation.AspNetCore A ASP.NET Core és a Kestrel rendszerállapota
OpenTelemetry.Instrumentation.GrpcNetClient GRPC-ügyfél rendszerállapota kimenő gRPC-hívások nyomon követéséhez
OpenTelemetry.Instrumentation.Http Kimenő HTTP-hívások rendszerezése HttpClient és HttpWebRequest nyomon követése
OpenTelemetry.Instrumentation.SqlClient Az adatbázis-műveletek SqlClient nyomon követésére szolgáló rendszerállapot
OpenTelemetry.Exporter.Console A konzol exportőre, amelyet gyakran használnak az exportálandó telemetriai adatok diagnosztizálására
OpenTelemetry.Exporter.OpenTelemetryProtocol Az OTLP protokollt használó exportőr
OpenTelemetry.Exporter.Prometheus.AspNetCore ASP.NET Core-végponttal implementált Prometheus-exportőr
OpenTelemetry.Exporter.Zipkin Zipkin-nyomkövetés exportőre

Példák

Ez a témakör néhány példaútmutatóval folytatódik az OpenTelemetry .NET-ben való használatához:

OpenTelemetry a .NET Aspire-ben

A .NET Aspire a .NET-bővítmények készlete, amelyek megkönnyítik az elosztott alkalmazások létrehozását és használatát. A .NET Aspire használatának egyik előnye, hogy a telemetria be van építve a .NET OpenTelemetry-kódtárainak használatával. A .NET Aspire alapértelmezett projektsablonjai tartalmaznak egy ServiceDefaults projektet, amelynek része az OTel beállítása és konfigurálása. A Service Defaults projektre minden szolgáltatás hivatkozik és inicializálódik egy .NET Aspire-megoldásban.

A Service Defaults projektsablon tartalmazza az OTel SDK, ASP.NET, HttpClient és Runtime Instrumentation csomagokat, és ezek a fájlban Extensions.cs vannak konfigurálva. A telemetria exportálásához a .NET Aspire alapértelmezés szerint tartalmazza az OTLP-exportőrt, hogy telemetriai vizualizációt biztosítson az Aspire irányítópult használatával.

Az Aspire-irányítópult úgy lett kialakítva, hogy telemetria-megfigyelést biztosítson a helyi hibakeresési ciklushoz, ami lehetővé teszi a fejlesztők számára, hogy ne csak telemetria-adatokat hozzanak létre, hanem a telemetriát is használják az alkalmazások helyi diagnosztizálásához. A szolgáltatások közötti hívások megfigyelése ugyanolyan hasznosnak bizonyul a hibakeresési időben, mint az éles környezetben. A .NET Aspire irányítópult automatikusan elindul, amikor a Visual Studióból vagy dotnet run a projektből F5-ként használja a AppHost AppHost projektet.

Aspire irányítópult

A .NET Aspire-ról további információt a következő témakörben talál:

A Service Defaults projekt újbóli használata .NET Aspire Orchestration nélkül

Valószínűleg az OTel ASP.NET projektekhez való konfigurálásának legegyszerűbb módja az Aspire Service Defaults projekt használata, még akkor is, ha nem használja a .NET Aspire többi részét, például az AppHostot vezénylésre. A Service Defaults projekt projektsablonként érhető el a Visual Studióban vagy dotnet newa . Konfigurálja az OTelt, és beállítja az OTLP-exportőrt. Ezután az OTel környezeti változókkal konfigurálhatja az OTLP-végpontot telemetriai adatok küldésére, és megadhatja az alkalmazás erőforrás-tulajdonságait.

A ServiceDefaults .NET Aspire-n kívüli használatának lépései a következők:

  • Adja hozzá a ServiceDefaults-projektet a megoldáshoz az Új projekt hozzáadása a Visual Studióban, vagy használja a dotnet new aspire-servicedefaults --output ServiceDefaults
  • Hivatkozzon a ServiceDefaults-projektre az ASP.NET alkalmazásból. A Visual Studióban használja a "Hozzáadás –> Projekthivatkozás" lehetőséget, és válassza ki a ServiceDefaults projektet
  • Hívja meg az OpenTelemetry telepítőfüggvényét az alkalmazásszerkesztő inicializálásának részeként.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

app.MapGet("/", () => "Hello World!");

app.Run();

A szolgáltatás alapértelmezései a következő további funkciókat állíthatják be, ha szükséges az adott függvényeken keresztül AddServiceDefaults() :

  • Állapot-ellenőrzések a végpontokkal és /alive a végpontokkal /health
  • Szolgáltatásfelderítés, amely a .NET Aspire többi tagja nélkül nem lesz művelet
  • A HttpClient rugalmasságának konfigurálása, amely hibák esetén újra megkísérli a kérést