Pozorovatelnost .NET pomocí OpenTelemetry

Když spustíte aplikaci, chcete vědět, jak dobře aplikace funguje, a zjistit potenciální problémy předtím, než se zvětší. Můžete to udělat tak, že vygenerujete telemetrická data, jako jsou protokoly nebo metriky z vaší aplikace, a pak tato data monitorujete a analyzujete.

Co je pozorovatelnost?

Pozorovatelnost v kontextu distribuovaného systému je schopnost monitorovat a analyzovat telemetrii o stavu jednotlivých komponent, aby bylo možné sledovat změny v výkonu a diagnostikovat, proč k těmto změnám dochází. Na rozdíl od ladění, které je invazivní a může ovlivnit provoz aplikace, je observabilita určena k tomu, aby byla transparentní pro primární operaci a měla dostatečně malý dopad na výkon, aby mohla být používána nepřetržitě.

Pozorovatelnost se běžně provádí pomocí kombinace:

  • Protokoly, které zaznamenávají jednotlivé operace, jako je příchozí požadavek, selhání v konkrétní komponentě nebo vytvoření objednávky.
  • Metriky, které měří čítače a měřidla, jako je počet dokončených požadavků, aktivní požadavky, widgety, které se prodaly, nebo histogram latence požadavku.
  • Distribuované trasování, které sleduje požadavky a aktivity napříč komponentami v distribuovaném systému, abyste viděli, kde je čas strávený, a sledovat konkrétní selhání.

Protokoly, metriky a distribuované trasování se někdy označují jako tři pilíře pozorovatelnosti.

Každý pilíř může obsahovat telemetrická data z:

  • Runtime .NET, například garbage collector nebo kompilátor JIT.
  • Knihovny, jako například Kestrel (ASP.NET webový server) a HttpClient.
  • Telemetrie specifická pro aplikaci, kterou váš kód vygeneruje.

Přístupy k pozorovatelnosti v .NET

Existuje několik různých způsobů, jak dosáhnout pozorovatelnosti v aplikacích .NET:

  • Explicitně v kódu pomocí odkazu na knihovnu, jako je OpenTelemetry. Pokud máte přístup ke zdrojovému kódu a můžete aplikaci znovu sestavit, jedná se o nejúčinnější a konfigurovatelný mechanismus.
  • Mimo proces pomocí EventPipe. Nástroje, jako dotnet-monitor, můžou naslouchat logům a metrikám a pak je zpracovávat, aniž by to ovlivnilo jakýkoli kód.
  • Pomocí spouštěcího háku lze sestavení vložit do procesu, který pak může shromažďovat instrumentaci. Příkladem tohoto přístupu je OpenTelemetry .NET Automatic Instrumentation.

Co je OpenTelemetry?

OpenTelemetry (OTel) je multiplatformní otevřený standard pro shromažďování a generování telemetrických dat. OpenTelemetry zahrnuje:

  • Rozhraní API pro knihovny, které se používají k zaznamenávání telemetrických dat během běhu kódu.
  • Rozhraní API , která vývojáři aplikací používají ke konfiguraci části zaznamenaných dat, která se budou odesílat přes síť, kam se budou odesílat a jak se můžou filtrovat, ukládat do vyrovnávací paměti, rozšiřovat a transformovat.
  • Sémantické konvence poskytují pokyny k pojmenování a obsahu telemetrických dat. Je důležité, aby aplikace, které vytvářejí telemetrická data, a nástroje, které obdrží data, souhlasily s tím, jaké různé druhy dat znamenají a jaké druhy dat jsou užitečné, aby nástroje mohly poskytovat efektivní analýzu.
  • Rozhraní pro vývozce. Exportéři jsou moduly plug-in, které umožňují přenos telemetrických dat v konkrétních formátech do různých back-endů telemetrie.
  • Protokol OTLP wire je síťový protokol nezávislý na dodavateli pro přenos telemetrických dat. Některé nástroje a dodavatelé podporují tento protokol kromě existujících vlastních protokolů, které mohou mít.

Použití OpenTelemetry umožňuje používat širokou škálu systémů APM, včetně opensourcových systémů, jako Prometheus a Grafana, Azure Monitor – produkt APM od Microsoftu na platformě Azure, nebo od mnoha dodavatelů APM spolupracujících s OpenTelemetry.

Pro většinu jazyků a platforem, včetně .NET, existují implementace OpenTelemetry.

Implementace OpenTelemetry pro .NET

Implementace .NET OpenTelemetry se trochu liší od jiných platforem, protože rozhraní .NET poskytuje rozhraní API pro protokolování, metriky a aktivity v rámci rozhraní API. To znamená, že OTel nemusí poskytovat rozhraní API pro autory knihoven, které by mohli používat. Implementace .NET OTel používá k instrumentaci tato rozhraní API platformy:

Architektura .NET OTel

Kde přichází do hry OTel, je to, že shromažďuje telemetrii z těchto rozhraní API a dalších zdrojů (prostřednictvím knihoven instrumentace) a pak je exportuje do systému APM (Application Performance Monitoring) aplikace pro ukládání a analýzu. Výhodou, kterou OTel přináší jako oborový standard, je běžný mechanismus pro shromažďování, běžná schémata a sémantika telemetrických dat a rozhraní API pro integraci apM s OTelem. Použití OTel znamená, že aplikace nemusí používat rozhraní API ani datové struktury specifické pro APM; pracují proti standardu OTel. APM mohou implementovat buď komponentu specifickou pro APM, nebo použít OTLP, což je nový standard pro přenos telemetrických dat do systémů APM.

Balíčky OpenTelemetry

OpenTelemetry v .NET se implementuje jako řada balíčků NuGet, které tvoří několik kategorií:

  • Základní rozhraní API
  • Instrumentace – tyto balíčky shromažďují instrumentaci z modulu runtime a běžných knihoven.
  • Vývozci – tyto se integrují se systémy pro správu výkonu aplikací (APM), jako jsou Prometheus, Jaeger a OTLP.

Následující tabulka popisuje hlavní balíčky.

Název balíčku Popis
OpenTelemetry Hlavní knihovna, která poskytuje základní funkce OTEL
OpenTelemetry.Instrumentation.AspNetCore Instrumentace pro ASP.NET Core a Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient Instrumentace pro klienta gRPC pro sledování odchozích volání gRPC
OpenTelemetry.Instrumentation.Http Instrumentace pro HttpClient a HttpWebRequest pro sledování odchozích volání HTTP
OpenTelemetry.Instrumentation.SqlClient Instrumentace použité pro SqlClient ke sledování databázových operací
OpenTelemetry.Exporter.Console Exportér konzoly, běžně používaný k diagnostice exportu telemetrie
OpenTelemetry.Exporter.OpenTelemetryProtocol Vývozce používající protokol OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore Exportér pro Prometheus implementovaný pomocí koncového bodu ASP.NET Core
OpenTelemetry.Exporter.Zipkin Exportér pro trasování Zipkin

Příklady

Toto téma pokračuje s několika příklady návodů pro použití OpenTelemetry v .NET:

OpenTelemetry v Aspire

Aspire je sada rozšíření, která .NET usnadňují vytváření a práci s distribuovanými aplikacemi. Jednou z výhod používání Aspire je, že telemetrie je integrovaná pomocí knihoven OpenTelemetry pro .NET. Výchozí šablony projektů pro Aspire projekt obsahují ServiceDefaults projekt, jehož součástí je nastavení a konfigurace OTelu. Na projekt Výchozí nastavení služby se odkazuje a inicializuje každá služba v Aspire řešení.

Šablona projektu Výchozí nastavení služby zahrnuje balíčky OTel SDK, ASP.NET, HttpClient a Runtime Instrumentation a ty jsou nakonfigurované v Extensions.cs souboru. Pro export telemetrie zahrnuje ve výchozím nastavení exportér OTLP, Aspire aby mohl poskytovat vizualizaci telemetrie pomocí řídicího panelu Aspire .

Řídicí Aspire panel je navržený tak, aby přinesl telemetrická pozorování do místního ladicího cyklu, což vývojářům umožňuje nejen zajistit, aby aplikace vytvářely telemetrii, ale také tato telemetrie používala k místní diagnostice těchto aplikací. Schopnost sledovat volání mezi službami se ukazuje, že je stejně užitečná v době ladění jako v produkčním prostředí. Řídicí panel Aspire se spustí automaticky, když stisknete F5 pro spuštění AppHost projektu z Visual Studia nebo dotnet runAppHost projektu.

Aspire Řídicí panel

Další podrobnosti najdete tady Aspire :

Opětovné použití projektu Služební výchozí nastavení bez použití Aspire orchestrace

Nejjednodušší způsob konfigurace OTelu pro projekty ASP.NET je použít projekt výchozích hodnot služby Aspire Service, i když nepoužíváte zbytek Aspire, jako je například AppHost pro orchestraci. Projekt Výchozí nastavení služby je k dispozici jako šablona projektu prostřednictvím sady Visual Studio nebo dotnet new. Nakonfiguruje OTel a nastaví vývozce OTLP. Pak můžete pomocí proměnných prostředí OTel nakonfigurovat koncový bod OTLP tak, aby odesílal telemetrii, a poskytnout vlastnosti prostředku pro aplikaci.

Postup použití ServiceDefaults mimo Aspire:

  • Přidejte projekt ServiceDefaults do řešení pomocí příkazu Přidat nový projekt v sadě Visual Studio nebo použijte dotnet new aspire-servicedefaults --output ServiceDefaults.
  • Odkaz na projekt ServiceDefaults z aplikace ASP.NET. Ve Visual Studio použijte Přidat>Odkaz na projekt a vyberte projekt ServiceDefaults.
  • Volejte funkci nastavení OpenTelemetry jako součást inicializace tvůrce aplikací.
var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Výchozí nastavení služby může v případě potřeby použít AddServiceDefaults() nebo konkrétní funkce k nastavení následujících funkcionalit:

  • Kontroly stavu u /health koncových bodů a /alive koncových bodů.
  • Zjišťování služeb, které nebude mít žádný účinek bez zbytku Aspire.
  • Konfigurace odolnosti pro HttpClient, která opakuje požadavky v případě selhání.
  • Last updated on