Obserwowanie platformy .NET za pomocą technologii OpenTelemetry

Po uruchomieniu aplikacji chcesz wiedzieć, jak dobrze działa aplikacja, oraz wykrywać potencjalne problemy, zanim staną się większe. Można to zrobić, emitując dane telemetryczne, takie jak dzienniki lub metryki z aplikacji, a następnie monitorując i analizując te dane.

Co to jest obserwowanie?

Obserwowanie w kontekście systemu rozproszonego to możliwość monitorowania i analizowania danych telemetrycznych dotyczących stanu każdego składnika, aby móc obserwować zmiany wydajności i diagnozować, dlaczego te zmiany występują. W przeciwieństwie do debugowania, który jest inwazyjny i może mieć wpływ na działanie aplikacji, obserwacja ma być niewidoczna dla operacji podstawowej i ma wystarczająco mały wpływ na wydajność, który może być używany w sposób ciągły.

Obserwacja jest często wykonywana przy użyciu kombinacji:

• Dzienniki, które rejestrują poszczególne operacje, takie jak żądanie przychodzące, błąd w określonym składniku lub złożone zamówienie.
• Metryki, które mierzyją liczniki i mierniki, takie jak liczba ukończonych żądań, aktywne żądania, sprzedane widżety lub histogram opóźnienia żądania.
• Śledzenie rozproszone, które śledzi żądania i działania między składnikami w systemie rozproszonym, dzięki czemu można zobaczyć, gdzie jest poświęcany czas i śledzić określone błędy.

Dzienniki, metryki i śledzenie rozproszone są czasami znane jako trzy filary obserwacji.

Każdy filar może obejmować dane telemetryczne z:

• Środowisko uruchomieniowe platformy .NET, takie jak moduł odśmiecania pamięci lub kompilator JIT.
• Biblioteki, takie jak kestrel (serwer internetowy ASP.NET) i HttpClient.
• Telemetria specyficzna dla aplikacji, która jest emitowana przez kod.

Podejścia do obserwacji na platformie .NET

Istnieje kilka różnych sposobów obserwowania w aplikacjach platformy .NET:

• Jawnie w kodzie, odwołując się do biblioteki i używając biblioteki, takiej jak OpenTelemetry. Jeśli masz dostęp do kodu źródłowego i możesz ponownie skompilować aplikację, jest to najbardziej zaawansowany i konfigurowalny mechanizm.
• Out-of-process using EventPipe.Out-of-process using EventPipe (Out-of-process using EventPipe). Narzędzia takie jak dotnet-monitor mogą nasłuchiwać dzienników i metryk, a następnie przetwarzać je bez wpływu na kod.
• Za pomocą haka startowego zestawy można wstrzykiwać do procesu, który może następnie zbierać instrumentację. Przykładem tej metody jest automatyczna instrumentacja platformy .NET OpenTelemetry.

Co to jest OpenTelemetry?

OpenTelemetry (OTel) to międzyplatformowy, otwarty standard zbierania i emitowania danych telemetrycznych. Funkcja OpenTelemetry obejmuje:

• Interfejsy API dla bibliotek do rejestrowania danych telemetrycznych w miarę uruchamiania kodu.
• Interfejsy API używane przez deweloperów aplikacji do konfigurowania, która część zarejestrowanych danych będzie wysyłana przez sieć, gdzie będzie ona wysyłana oraz jak może być filtrowana, buforowana, wzbogacona i przekształcana.
• Konwencje semantyczne zawierają wskazówki dotyczące nazewnictwa i zawartości danych telemetrycznych. Ważne jest, aby aplikacje generujące dane telemetryczne i narzędzia odbierające dane uzgodniły, jakie rodzaje danych oznaczają i jakie rodzaje danych są przydatne, aby narzędzia mogły zapewnić skuteczną analizę.
• Interfejs dla eksporterów. Eksporterzy to wtyczki, które umożliwiają przesyłanie danych telemetrycznych w określonych formatach do różnych zapleczy telemetrii.
• Protokół przewodowy OTLP to neutralna dla dostawcy opcja protokołu sieciowego do przesyłania danych telemetrycznych. Niektóre narzędzia i dostawcy obsługują ten protokół oprócz istniejących protokołów własnościowych, które mogą mieć.

Korzystanie z systemu OTel umożliwia korzystanie z wielu różnych systemów APM, w tym systemów typu open source, takich jak Prometheus i Grafana, Azure Monitor — produkt APM firmy Microsoft na platformie Azure lub wielu dostawców APM, którzy współpracuje z usługą OpenTelemetry.

Istnieją implementacje openTelemetry dla większości języków i platform, w tym .NET.

Implementacja platformy .NET technologii OpenTelemetry

Implementacja platformy .NET OpenTelemetry różni się nieco od innych platform, ponieważ platforma .NET udostępnia interfejsy API rejestrowania, metryk i aktywności w strukturze. Oznacza to, że usługa OTel nie musi udostępniać interfejsów API dla autorów bibliotek do użycia. Implementacja platformy .NET OTel używa tych interfejsów API platformy do instrumentacji:

• Microsoft.Extensions.Logging.ILogger<TCategoryName>do rejestrowania
• System.Diagnostics.Metrics.Meter dla metryk
• System.Diagnostics.ActivitySource i System.Diagnostics.Activity do śledzenia rozproszonego

Gdzie OTel wchodzi w grę, jest to, że zbiera dane telemetryczne z tych interfejsów API i innych źródeł (za pośrednictwem bibliotek instrumentacji), a następnie eksportuje je do systemu monitorowania wydajności aplikacji (APM) na potrzeby magazynowania i analizy. Zaletą, jaką firma OTel oferuje jako standard branżowy, jest wspólny mechanizm zbierania, typowych schematów i semantyki danych telemetrycznych oraz interfejsu API służącego do integrowania usługi APM z usługą OTel. Korzystanie z protokołu OTel oznacza, że aplikacje nie muszą używać interfejsów API specyficznych dla APM ani struktur danych; działają one przeciwko standardowi OTel. ApMs może zaimplementować składnik eksportera specyficznego dla APM lub użyć OTLP, który jest nowym standardem przewodu do eksportowania danych telemetrycznych do systemów APM.

Pakiety OpenTelemetry

Funkcja OpenTelemetry na platformie .NET jest implementowana jako seria pakietów NuGet, które tworzą kilka kategorii:

• Podstawowy interfejs API
• Instrumentacja — te pakiety zbierają instrumentację ze środowiska uruchomieniowego i wspólnych bibliotek.
• Eksporterzy — te interfejsy z systemami APM, takimi jak Prometheus, Jaeger i OTLP.

W poniższej tabeli opisano główne pakiety.

Nazwa pakietu	opis
OpenTelemetry	Główna biblioteka zapewniająca podstawowe funkcje OTEL
OpenTelemetry.Instrumentation.AspNetCore	Instrumentacja dla ASP.NET Core i Kestrel
OpenTelemetry.Instrumentation.GrpcNetClient	Instrumentacja dla klienta gRPC do śledzenia wychodzących wywołań gRPC
OpenTelemetry.Instrumentation.Http	Instrumentacja i HttpClient HttpWebRequest śledzenie wychodzących wywołań HTTP
OpenTelemetry.Instrumentation.SqlClient	Instrumentacja używana SqlClient do śledzenia operacji bazy danych
OpenTelemetry.Exporter.Console	Eksporter dla konsoli, często używany do diagnozowania, jakie dane telemetryczne są eksportowane
OpenTelemetry.Exporter.OpenTelemetryProtocol	Eksporter używający protokołu OTLP
OpenTelemetry.Exporter.Prometheus.AspNetCore	Eksporter dla rozwiązania Prometheus zaimplementowany przy użyciu punktu końcowego podstawowego ASP.NET
OpenTelemetry.Exporter.Zipkin	Eksporter do śledzenia Zipkin

Przykłady

Ten temat jest kontynuowany z kilkoma przykładowymi przewodnikami dotyczącymi używania biblioteki OpenTelemetry na platformie .NET:

• Przykład: Używanie programu OTLP i autonomicznego pulpitu nawigacyjnego Aspire
• Przykład: używanie biblioteki OpenTelemetry z usługami Azure Monitor i Application Insights
• Przykład: używanie funkcji OpenTelemetry z rozwiązaniem Prometheus, Grafana i Jaeger

OpenTelemetry na platformie .NET Aspire

.NET Aspire to zestaw rozszerzeń platformy .NET, który ułatwia tworzenie i pracę z aplikacjami rozproszonymi. Jedną z zalet korzystania z platformy .NET Aspire jest wbudowana telemetria przy użyciu bibliotek OpenTelemetry dla platformy .NET. Domyślne szablony projektów dla platformy .NET Aspire zawierają ServiceDefaults projekt, którego częścią jest konfigurowanie i konfigurowanie aplikacji OTel. Projekt Ustawienia domyślne usługi jest przywołytyty i inicjowany przez każdą usługę w rozwiązaniu .NET Aspire.

Szablon projektu Ustawienia domyślne usługi zawiera pakiety OTel SDK, ASP.NET, HttpClient i Instrumentation środowiska uruchomieniowego Extensions.cs , a te są konfigurowane w pliku. W przypadku eksportowania telemetrii .NET Aspire domyślnie obejmuje eksportera OTLP, dzięki czemu może zapewnić wizualizację telemetrii przy użyciu pulpitu nawigacyjnego Aspirującego.

Pulpit nawigacyjny Aspirującego został zaprojektowany w celu umożliwienia obserwacji telemetrii w lokalnym cyklu debugowania, co umożliwia deweloperom nie tylko zapewnienie, że aplikacje generują dane telemetryczne, ale także używają tej telemetrii do diagnozowania tych aplikacji lokalnie. Możliwość obserwowania wywołań między usługami okazuje się równie przydatna w czasie debugowania, jak w środowisku produkcyjnym. Pulpit nawigacyjny platformy .NET Aspire jest uruchamiany automatycznie po uruchomieniu AppHost AppHost projektu F5 z programu Visual Studio lub dotnet run projektu.

Aby uzyskać więcej informacji na temat platformy .NET Aspire, zobacz:

• Przegląd Aspiruj
• Telemetria w Aspiruj
• Aspiruj pulpit nawigacyjny

Ponowne używanie projektu Domyślne usługi bez orkiestracji aspirujących platformy .NET

Prawdopodobnie najprostszym sposobem skonfigurowania biblioteki OTel dla projektów ASP.NET jest użycie projektu Aspirowanie domyślnych usług, nawet jeśli nie używasz pozostałej części platformy .NET Aspire, takiej jak AppHost do orkiestracji. Projekt Ustawienia domyślne usługi jest dostępny jako szablon projektu za pośrednictwem programu Visual Studio lub dotnet new. Konfiguruje OTel i konfiguruje eksportera OTLP. Następnie możesz użyć zmiennych środowiskowych OTel, aby skonfigurować punkt końcowy OTLP do wysyłania danych telemetrycznych i podać właściwości zasobu dla aplikacji.

Kroki korzystania z usługi ServiceDefaults poza platformą .NET Aspire są następujące:

• Dodaj projekt ServiceDefaults do rozwiązania przy użyciu polecenia Dodaj nowy projekt w programie Visual Studio lub użyj poleceniadotnet new aspire-servicedefaults --output ServiceDefaults
• Odwołaj się do projektu ServiceDefaults z aplikacji ASP.NET. W programie Visual Studio użyj polecenia "Dodaj —> odwołanie do projektu" i wybierz projekt ServiceDefaults .
• Wywołaj funkcję konfiguracji OpenTelemetry w ramach inicjowania konstruktora aplikacji.

var builder = WebApplication.CreateBuilder(args);
builder.ConfigureOpenTelemetry();

var app = builder.Build();

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

app.Run();

Ustawienia domyślne usługi mogą skonfigurować następujące dodatkowe funkcje, jeśli są wymagane za pośrednictwem AddServiceDefaults() lub określonych funkcji:

• Kontrole kondycji z punktami /health końcowymi i /alive
• Odnajdywanie usług, które nie będzie działać bez reszty platformy .NET Aspire
• Konfigurowanie odporności dla klienta HttpClient, który ponowi próbę żądania w przypadku awarii