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óre jest inwazyjne i może wpływać na działanie aplikacji, obserwowalność jest przeznaczona do bycia przejrzystą dla podstawowej operacji i ma na tyle mały wpływ na wydajność, aby mogła być używana 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 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.
  • Proces poza wątkiem z użyciem 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 tego podejścia jest OpenTelemetry .NET Automatic Instrumentation.

Co to jest OpenTelemetry?

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

  • API dla bibliotek do rejestrowania danych telemetrycznych w czasie działania 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:

Architektura OTel .NET

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:

  • Główne API
  • Instrumentacja — te pakiety zbierają instrumentację ze środowiska uruchomieniowego i wspólnych bibliotek.
  • Eksporterzy — współpracują 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 dla HttpClient i HttpWebRequest w celu śledzenia wychodzących wywołań HTTP
OpenTelemetry.Instrumentation.SqlClient Instrumentacja dla SqlClient używana 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 Prometheus zaimplementowany przy użyciu punktu końcowego ASP.NET Core.
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:

OpenTelemetry in Aspire

Aspire jest zestawem rozszerzeń do .NET, aby ułatwić tworzenie i pracę z aplikacjami rozproszonymi. Jedną z zalet korzystania z Aspire jest to, że telemetria jest wbudowana przy użyciu bibliotek OpenTelemetry dla .NET. Domyślne szablony projektów dla Aspire zawierają projekt ServiceDefaults, którego częścią jest skonfigurowanie i konfiguracja OTel. Projekt Service Defaults jest odwoływany i inicjowany przez każdą usługę w rozwiązaniu Aspire.

Szablon projektu Domyślne ustawienia usługi zawiera pakiety OTel SDK, ASP.NET, HttpClient oraz Instrumentation środowiska uruchomieniowego Extensions.cs, a te są konfigurowane w pliku. W przypadku eksportowania danych telemetrycznych domyślnie zawiera eksportera OTLP, Aspire dzięki czemu może udostępniać wizualizację telemetrii przy użyciu pulpitu nawigacyjnego Aspire .

Pulpit Aspire nawigacyjny 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. Panel kontrolny Aspire jest uruchamiany automatycznie, gdy uruchomisz F5AppHost Projekt z Visual Studio lub dotnet runAppHost projekt.

Aspire Pulpitu nawigacyjnego

Aby uzyskać więcej informacji na temat tego tematu Aspire , zobacz:

Ponowne użycie projektu ustawienia domyślne usługi bez Aspire orkiestracji

Prawdopodobnie najprostszym sposobem skonfigurowania protokołu OTel dla projektów ASP.NET jest użycie projektu Aspire Service Defaults, nawet jeśli nie używa pozostałej części Aspire, takiej jak AppHost do orkiestracji. Projekt Domyślne ustawienia usługi jest dostępny jako szablon projektu za pośrednictwem programu Visual Studio lub dotnet new. Konfiguruje OTel i ustawia 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 elementu ServiceDefaults na zewnątrz Aspire to:

  • Dodaj projekt ServiceDefaults do rozwiązania przy użyciu polecenia Dodaj nowy projekt w programie Visual Studio lub użyj polecenia dotnet new aspire-servicedefaults --output ServiceDefaults.
  • Odwołaj się do projektu ServiceDefaults z aplikacji ASP.NET. W programie Visual Studio użyj pozycji 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();

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

  • Kontrole zdrowia z końcowymi punktami /health i /alive.
  • Odkrywanie usług, które nie wykona żadnej operacji bez reszty Aspire.
  • Konfigurowanie niezawodności dla HttpClient, która ponawia żądania w przypadku awarii.
  • Last updated on