Udostępnij za pośrednictwem

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 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 konwersja i konfiguracja OTel. Projekt Ustawienia domyślne usługi jest przywoływany i inicjowany przez każdą usługę w rozwiązaniu .NET 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 telemetrii .NET Aspire domyślnie obejmuje eksportera OTLP, dzięki czemu może zapewnić wizualizację telemetrii przy użyciu pulpitu nawigacyjnego Aspire.

Panel kontrolny Aspire został zaprojektowany w celu umożliwienia monitorowania telemetrii w lokalnym procesie debugowania, co pozwala deweloperom nie tylko upewnić się, że aplikacje generują dane telemetryczne, ale także używać tych danych do lokalnej diagnozy tych aplikacji. 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, gdy naciśniesz klawisz F5 dla projektu AppHost z programu Visual Studio lub projektu dotnet run.

Aspire Panel kontrolny

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

Projekt ponownego używania domyślnych ustawień serwerowych bez zarządzania Aspire w ramach platformy .NET

Prawdopodobnie najprostszym sposobem skonfigurowania OpenTelemetry dla projektów ASP.NET jest skorzystanie z projektu Aspire Service Defaults, nawet jeśli nie używasz innych elementów platformy .NET Aspire, takich jak AppHost do zadań orkiestracyjnych. 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 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 zdrowia z punktami końcowymi /health 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