Udostępnij za pośrednictwem

Przykład: używanie biblioteki OpenTelemetry z funkcją OTLP i autonomicznym pulpitem nawigacyjnym Aspire

  • Artykuł

Jest to jedna z serii przykładów ilustrujących możliwość obserwowania platformy .NET za pomocą technologii OpenTelemetry.

Oprócz standardowej części platformy .NET Aspire pulpit nawigacyjny Aspiruje jest dostępny jako autonomiczny kontener platformy Docker, który zapewnia telemetrię punktu końcowego OTLP, do którego można wysyłać dane telemetryczne i wizualizuje dzienniki, metryki i ślady. Korzystanie z pulpitu nawigacyjnego w ten sposób nie ma zależności od platformy .NET Aspire, będzie wizualizować dane telemetryczne z dowolnej aplikacji wysyłającej dane telemetryczne za pośrednictwem funkcji OTLP. Działa równie dobrze w przypadku aplikacji napisanych w języku Java, GoLang, Python itp. pod warunkiem, że mogą wysyłać dane telemetryczne do punktu końcowego OTLP.

Korzystanie z pulpitu nawigacyjnego Aspirującego ma mniej konfiguracji i kroków konfiguracji niż korzystanie z rozwiązań typu open source, takich jak Prometheus, Grafana i Jaeger, ale w przeciwieństwie do tych narzędzi, pulpit nawigacyjny Aspire jest przeznaczony jako narzędzie do wizualizacji deweloperów, a nie do monitorowania produkcyjnego.

1. Tworzenie projektu

Utwórz prosty projekt internetowego interfejsu API przy użyciu szablonu ASP.NET Core Empty w programie Visual Studio lub następującego polecenia interfejsu wiersza polecenia platformy .NET:

dotnet new web

2. Dodawanie metryk i definicji działań

Poniższy kod definiuje nową metrykę (greetings.count) dla liczby wywołań interfejsu API i nowego źródła działań (Otel.Example).

// Custom metrics for the application
var greeterMeter = new Meter("OTel.Example", "1.0.0");
var countGreetings = greeterMeter.CreateCounter<int>("greetings.count", description: "Counts the number of greetings");

// Custom ActivitySource for the application
var greeterActivitySource = new ActivitySource("OTel.Example");

3. Tworzenie punktu końcowego interfejsu API

Wstaw następujące elementy między builder.Build(); i app.Run()

app.MapGet("/", SendGreeting);

Wstaw następującą funkcję w dolnej części pliku:

async Task<String> SendGreeting(ILogger<Program> logger)
{
    // Create a new Activity scoped to the method
    using var activity = greeterActivitySource.StartActivity("GreeterActivity");

    // Log a message
    logger.LogInformation("Sending greeting");

    // Increment the custom counter
    countGreetings.Add(1);

    // Add a tag to the Activity
    activity?.SetTag("greeting", "Hello World!");

    return "Hello World!";
}

Uwaga

Definicja punktu końcowego nie używa żadnych elementów specyficznych dla funkcji OpenTelemetry. Używa on interfejsów API platformy .NET do obserwowania.

4. Odwołanie do pakietów OpenTelemetry

Użyj Menedżer pakietów NuGet lub wiersza polecenia, aby dodać następujące pakiety NuGet:

  <ItemGroup>
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Extensions.Hosting" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.AspNetCore" Version="1.9.0" />
    <PackageReference Include="OpenTelemetry.Instrumentation.Http" Version="1.9.0" />
  </ItemGroup>

Uwaga

Użyj najnowszych wersji, ponieważ interfejsy API OTel stale ewoluują.

5. Konfigurowanie biblioteki OpenTelemetry przy użyciu odpowiednich dostawców

Wstaw następujący kod przed :builder.Build();

// Setup logging to be exported via OpenTelemetry
builder.Logging.AddOpenTelemetry(logging =>
{
    logging.IncludeFormattedMessage = true;
    logging.IncludeScopes = true;
});

var otel = builder.Services.AddOpenTelemetry();

// Add Metrics for ASP.NET Core and our custom metrics and export via OTLP
otel.WithMetrics(metrics =>
{
    // Metrics provider from OpenTelemetry
    metrics.AddAspNetCoreInstrumentation();
    //Our custom metrics
    metrics.AddMeter(greeterMeter.Name);
    // Metrics provides by ASP.NET Core in .NET 8
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");
});

// Add Tracing for ASP.NET Core and our custom ActivitySource and export via OTLP
otel.WithTracing(tracing =>
{
    tracing.AddAspNetCoreInstrumentation();
    tracing.AddHttpClientInstrumentation();
    tracing.AddSource(greeterActivitySource.Name);
});

// Export OpenTelemetry data via OTLP, using env vars for the configuration
var OtlpEndpoint = builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"];
if (OtlpEndpoint != null)
{
    otel.UseOtlpExporter();
}

Ten kod konfiguruje usługę OpenTelemetry z różnymi źródłami telemetrii:

  • Dodaje dostawcę OTel do usługi ILogger w celu zbierania rekordów dzienników.
  • Konfiguruje metryki, rejestrując dostawców instrumentacji i mierniki dla ASP.NET i naszego niestandardowego miernika.
  • Konfiguruje śledzenie, rejestrowanie dostawców instrumentacji i niestandardowe źródło działań.

Następnie rejestruje eksportera OTLP przy użyciu wariantów env dla jego konfiguracji.

6. Konfigurowanie zmiennych środowiskowych OTLP

Eksporter OTLP można skonfigurować za pośrednictwem interfejsów API w kodzie, ale jego częściej konfiguruje go za pomocą zmiennych środowiskowych. Dodaj następujące elementy do AppSettings.Development.json

"OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
"OTEL_SERVICE_NAME": "OTLP-Example"

Możesz dodać dodatkowe zmienne środowiskowe dla eksportera OTLP platformy .NET lub typowe zmienne OTel, takie jak OTEL_RESOURCE_ATTRIBUTES definiowanie atrybutów zasobów.

Uwaga

Typowe gotcha polega na mieszaniu AppSettings.json i AppSettings.Development.json, jeśli ten ostatni jest obecny, będzie używany podczas F5 z programu Visual Studio i wszelkie ustawienia w AppSettings.json zostaną zignorowane.

7. Uruchamianie kontenera Pulpit nawigacyjny Aspirujący

Użyj platformy Docker, aby pobrać i uruchomić kontener pulpitu nawigacyjnego.

docker run --rm -it `
-p 18888:18888 `
-p 4317:18889 `
--name aspire-dashboard `
mcr.microsoft.com/dotnet/aspire-dashboard:latest

Dane wyświetlane na pulpicie nawigacyjnym mogą być poufne. Domyślnie pulpit nawigacyjny jest zabezpieczony przy użyciu uwierzytelniania, które wymaga tokenu do zalogowania. Token jest wyświetlany w wynikowych danych wyjściowych podczas uruchamiania kontenera.

[Aspiruj pulpit nawigacyjny]

Skopiuj wyświetlony adres URL i zastąp localhostciąg 0.0.0.0 , nphttp://localhost:18888/login?t=123456780abcdef123456780. i otwórz go w przeglądarce lub możesz również wkleić klucz po /login?t= wyświetleniu okna dialogowego logowania. Token zmieni się za każdym razem, gdy uruchomisz kontener.

8. Uruchamianie projektu

Uruchom projekt, a następnie uzyskaj dostęp do interfejsu API za pomocą przeglądarki lub narzędzia curl.

curl -k http://localhost:7275

Za każdym razem, gdy zażądasz strony, będzie ona zwiększać liczbę wykonanych powitań.

8.1 Dane wyjściowe dziennika

Instrukcje rejestrowania z kodu są danymi wyjściowymi przy użyciu polecenia ILogger. Domyślnie dostawca konsoli jest włączony, aby dane wyjściowe są kierowane do konsoli.

Istnieje kilka opcji, w jaki sposób dzienniki mogą być wychodzące z platformy .NET:

  • stdout dane wyjściowe są stderr przekierowywane do plików dziennika przez systemy kontenerów, takie jak Kubernetes.
  • Korzystając z bibliotek rejestrowania, które zostaną zintegrowane z usługą ILogger, należą do nich serilog lub NLog.
  • Używanie dostawców rejestrowania dla technologii OTel, takich jak OTLP. Sekcja rejestrowania w kodzie z kroku 5 dodaje dostawcę OTel.

Dzienniki są wyświetlane na pulpicie nawigacyjnym jako dzienniki ustrukturyzowane — wszystkie właściwości ustawione w komunikacie dziennika są wyodrębniane jako pola w rekordzie dziennika.

Dzienniki na autonomicznym pulpicie nawigacyjnym

8.2 Wyświetlanie metryk

Pulpit nawigacyjny Aspire pokazuje metryki dla poszczególnych zasobów (zasób jest sposobem OTel mówienia o źródłach danych telemetrycznych, takich jak proces). Po wybraniu zasobu pulpit nawigacyjny będzie wyliczał każdą metrykę, która została wysłana do punktu końcowego OTLP przez zasób. Lista metryk jest dynamiczna i zostanie zaktualizowana w miarę odbierania nowych metryk.

Metryki na autonomicznym pulpicie nawigacyjnym

Widok metryk będzie zależeć od typu używanej metryki:

  • Liczniki będą wyświetlane bezpośrednio.
  • Histogramy, które śledzą wartość na żądanie, takie jak przedział czasu lub bajty wysyłane na żądanie, są zbierane w serii zasobników. Pulpit nawigacyjny będzie grafem percentyli P50, P90 i P99. Wyniki histogramu mogą zawierać przykłady, które są poszczególnymi punktami danych wraz z identyfikatorem trace/spanId dla tego żądania. Będą one wyświetlane jako kropki na grafie. Wybranie elementu spowoduje przejście do odpowiedniego śladu, aby zobaczyć, co się stało, aby spowodować tę wartość. Jest to przydatne w przypadku diagnozowania wartości odstających.
  • Metryki mogą zawierać wymiary, które są parami klucz/wartość skojarzonymi z poszczególnymi wartościami. Wartości są agregowane na wymiar. Korzystając z list rozwijanych w widoku, można filtrować wyniki, aby przyjrzeć się określonym wymiarom, takim jak tylko GET żądania, lub dla określonej trasy adresu URL w ASP.NET.

8.3 Wyświetlanie śledzenia

W widoku śledzenia zostanie wyświetlona lista śladów — każdy ślad jest zestawem działań, które współużytkują ten sam identyfikator traceId. Praca jest śledzona za pomocą zakresów reprezentujących jednostkę pracy. Przetwarzanie żądania ASP.NET spowoduje utworzenie zakresu. Tworzenie żądania HttpClient będzie zakresem. Śledząc element nadrzędny zakresu, można zwizualizować hierarchię zakresów. Zbierając zakresy z każdego zasobu (procesu), śledzimy pracę wykonywaną w ramach serii usług. Żądania HTTP mają nagłówek, który jest używany do przekazywania traceId i parent spanId do następnej usługi. Każdy zasób musi zbierać dane telemetryczne i wysyłać je do tego samego modułu zbierającego. Następnie będzie agregować i przedstawiać hierarchię zakresów.

Ślady na autonomicznym pulpicie nawigacyjnym

Na pulpicie nawigacyjnym zostanie wyświetlona lista śladów z informacjami podsumowującymi. Za każdym razem, gdy są widoczne nowe identyfikatory traceId, otrzymają wiersz w tabeli. Kliknięcie widoku spowoduje wyświetlenie wszystkich zakresów w śladzie.

Zakresy na autonomicznym pulpicie nawigacyjnym

Wybranie zakresu spowoduje wyświetlenie jego szczegółów, w tym wszelkich właściwości w zakresie, takich jak greeting tag ustawiony w kroku 3.