Sdílet prostřednictvím

Pozorovatelnost .NET pomocí OpenTelemetry

  • Článek

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í, což je invazní a může ovlivnit provoz aplikace, je pozorovatelnost pro primární operaci transparentní a má malý dostatečný dopad na výkon, který lze používat 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 pořadí.
  • 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:

  • Modul runtime .NET, například uvolňování paměti nebo kompilátor JIT.
  • Knihovny, jako je 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.
  • Out-of-process using EventPipe. Nástroje, jako je dotnet-monitor , můžou naslouchat protokolů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 automatická instrumentace OpenTelemetry .NET.

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, když je spuštěný kód.
  • 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.
  • Wire Protocol OTLP je možnost přenosu telemetrických dat neutrálním síťovým protokolem dodavatele. Některé nástroje a dodavatelé podporují tento protokol kromě existujících vlastních protokolů, které mohou mít.

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

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

Implementace .NET OpenTelemetry

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 buď implementovat komponentu specifického vývozce APM, nebo použít OTLP, což je nový standard drátu pro export 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 – tato rozhraní se systémy 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 sledování odchozích volání HTTP
OpenTelemetry.Instrumentation.SqlClient Instrumentace pro SqlClient použití 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í zipů

Příklady

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

OpenTelemetry v .NET Aspire

.NET Aspire je sada rozšíření .NET, která usnadňují vytváření a práci s distribuovanými aplikacemi. Jednou z výhod použití rozhraní .NET Aspire je, že telemetrie je integrovaná pomocí knihoven OpenTelemetry pro .NET. Výchozí šablony projektů pro .NET Aspire 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 řešení .NET Aspire.

Š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 .NET Aspire ve výchozím nastavení zahrnuje vývozce OTLP, aby mohl poskytnout vizualizaci telemetrie pomocí řídicího panelu Aspire.

Řídicí panel Aspire je navržený tak, aby přinesl telemetrická pozorování do místního cyklu ladění, což vývojářům umožňuje nejen zajistit, aby aplikace vytvářely telemetrii, ale také tuto telemetrii používají 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 .NET Aspire se spustí automaticky při F5 AppHost projektu ze sady Visual Studio nebo dotnet run AppHost projektu.

Aspire Dashboard

Další podrobnosti o .NET Aspire najdete tady:

Opětovné použití projektu Výchozí nastavení služby bez orchestrace .NET Aspire

Pravděpodobně nejjednodušší způsob, jak nakonfigurovat OTel pro ASP.NET projekty, je použít projekt Výchozí služby Aspire, i když nepoužíváte zbytek rozhraní .NET Aspire, jako je 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 rozhraní .NET Aspire:

  • Přidejte projekt ServiceDefaults do řešení pomocí příkazu Přidat nový projekt v sadě Visual Studio nebo použijtedotnet new aspire-servicedefaults --output ServiceDefaults
  • Odkaz na projekt ServiceDefaults z aplikace ASP.NET. V sadě Visual Studio použijte příkaz 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 prostřednictvím AddServiceDefaults() konkrétních funkcí nastavit následující další funkce:

  • Kontroly stavu s /health koncovými body a /alive koncovými body
  • Zjišťování služeb, které bude no-op bez zbytku rozhraní .NET Aspire
  • Konfigurace odolnosti pro HttpClient, která bude požadavek opakovat v případě selhání