Używanie funkcji OpenTelemetry z funkcją OTLP i pulpitem nawigacyjnym Aspire

W tym artykule pokazano, jak instrumentować internetowy interfejs API .NET za pomocą biblioteki OpenTelemetry i wysyłać dzienniki, metryki i ślady do pulpitu nawigacyjnego Aspire przy użyciu funkcji OTLP. Dodasz pakiety OpenTelemetry, skonfigurujesz niestandardowe metryki i ślady oraz wyświetlisz wyniki na pulpicie nawigacyjnym.

Panel Aspire jest standardową częścią Aspire, ale jest również dostępny jako samodzielny kontener Docker, który udostępnia punkt końcowy OTLP do wysyłania danych telemetrycznych. Panel wizualizuje dzienniki, metryki i ślady. Korzystanie z panelu w ten sposób nie jest zależne od Aspire i umożliwia wizualizację telemetrii z dowolnej aplikacji, która wysyła ją za pomocą protokołu OTLP. Działa równie dobrze w przypadku aplikacji napisanych w Java, Go lub Python, pod warunkiem, że mogą wysyłać dane telemetryczne do punktu końcowego OTLP.

Pulpit Aspire nawigacyjny wymaga mniejszej konfiguracji i mniejszej liczby kroków konfiguracji niż rozwiązania typu open source, takie jak Prometheus, Grafana i Jaeger. Jednak w przeciwieństwie do tych narzędzi Aspire pulpit nawigacyjny jest narzędziem do wizualizacji dla deweloperów, a nie narzędziem do monitorowania produkcyjnego.

1. Tworzenie projektu

Utwórz prosty projekt internetowego interfejsu API, korzystając z szablonu ASP.NET Core Empty w programie Visual Studio lub następującego polecenia CLI platformy .NET:

dotnet new web

2. Dodaj odwołania do pakietów OpenTelemetry

Aby dodać pakiety OpenTelemetry, użyj Menedżer pakietów NuGet lub uruchom następujące dotnet add package polecenia:

dotnet add package OpenTelemetry.Exporter.OpenTelemetryProtocol
dotnet add package OpenTelemetry.Extensions.Hosting
dotnet add package OpenTelemetry.Instrumentation.AspNetCore
dotnet add package OpenTelemetry.Instrumentation.Http

Alternatywnie dodaj następujące PackageReference elementy bezpośrednio do pliku projektu:

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

Uwaga

Ponieważ interfejsy API OTel stale ewoluują, użyj najnowszych wersji.

3. Dodaj dyrektywy using

Dodaj następujące using dyrektywy na początku pliku:

using System.Diagnostics;
using System.Diagnostics.Metrics;
using OpenTelemetry.Exporter;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

4. Dodawanie metryk i definicji działań

Poniższy kod definiuje nową metrykę (greetings.count), która zlicza liczbę wywołań interfejsu API przez klienta oraz nowe źródło działań (Otel.Example). Wstaw ten kod przed builder.Build:

// 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");

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

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

// Configure the shared OTLP connection used by logs, metrics, and traces.
var otlpEndpoint = new Uri(builder.Configuration["OTEL_EXPORTER_OTLP_ENDPOINT"]!);
Action<OtlpExporterOptions> configureOtlp = options =>
{
    options.Endpoint = otlpEndpoint;
    options.Protocol = OtlpExportProtocol.Grpc;
    options.Headers = builder.Configuration["OTEL_EXPORTER_OTLP_HEADERS"]; // To secure endpoint (not in this example)
};

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

var otel = builder.Services.AddOpenTelemetry();

// Identify this application as a single service in the Aspire dashboard.
otel.ConfigureResource(resource => resource.AddService(builder.Configuration["OTEL_SERVICE_NAME"]!));

// 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 provided by ASP.NET Core in .NET
    metrics.AddMeter("Microsoft.AspNetCore.Hosting");
    metrics.AddMeter("Microsoft.AspNetCore.Server.Kestrel");

    // Export the metrics via OTLP
    metrics.AddOtlpExporter(configureOtlp);
});

// 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);
    tracing.AddOtlpExporter(configureOtlp);
});

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

• Dodaje dostawcę OTel do ILogger, aby zbierać wpisy dziennika.
• Konfiguruje metryki, rejestrując dostawców instrumentacji i mierniki dla ASP.NET i miernika niestandardowego.
• Konfiguruje śledzenie, rejestrowanie dostawców instrumentacji i niestandardowe ActivitySource.

Następnie rejestruje eksportera OTLP, używając zmiennych środowiskowych do jego konfiguracji.

6. Konfigurowanie ustawień OTLP

Eksporter OTLP można skonfigurować za pomocą interfejsów API w kodzie, zmiennych środowiskowych lub konfiguracji aplikacji. W tym przykładzie dodaj ustawienia OTLP w elemencie głównym appsettings.Development.json, po sekcji Logging:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "OTEL_EXPORTER_OTLP_ENDPOINT": "http://localhost:4317",
  "OTEL_SERVICE_NAME": "OTLP-Example"
}

Dodaj inne ustawienia eksportera OTLP platformy .NET lub wspólne ustawienia OTel, na przykład OTEL_RESOURCE_ATTRIBUTES, aby zdefiniować atrybuty zasobu.

Uwaga

ASP.NET Core ładuje zarówno elementy , jak appsettings.json i appsettings.Development.json. Ustawienia w pliku appsettings.Development.json zastępują zduplikowane ustawienia w pliku appsettings.json podczas uruchamiania aplikacji w środowisku Development.

7. Tworzenie punktu końcowego interfejsu API

Wstaw następujący kod 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 obserwowalności.

8. Uruchamianie kontenera pulpitu nawigacyjnego Aspire

Użyj docker do pobrania i uruchomienia kontenera 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 wymaga tokenu uwierzytelniania do logowania. Kontener wyświetla ten token w danych wyjściowych.

Skopiuj adres URL, zastąp localhost ciągiem 0.0.0.0, na przykład http://localhost:18888/login?t=123456780abcdef123456780, i otwórz go w przeglądarce. Możesz też wkleić klucz po /login?t= w oknie dialogowym logowania. Token zmienia się za każdym razem, gdy uruchamiasz kontener.

9. Uruchamianie projektu

Uruchom projekt za pomocą polecenia dotnet run. Dane wyjściowe w konsoli wyświetlają adresy URL, na których nasłuchuje aplikacja, na przykład:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5086

Użyj portu wyświetlanego we własnych danych wyjściowych konsoli, ponieważ może się różnić od przykładów w tym artykule. Użyj przeglądarki lub narzędzia curl, aby uzyskać dostęp do interfejsu API na tym porcie:

curl -k http://localhost:5086

Za każdym razem, gdy zażądasz strony, liczba powitań zwiększa się.

9.1 Dane wyjściowe dziennika

Kod rejestruje instrukcje za pomocą ILogger. Domyślnie .NET włącza dostawcę konsoli, który kieruje dane wyjściowe do konsoli.

Dzienniki z platformy .NET można eksportować na kilka sposobów:

• Systemy kontenerowe, takie jak Kubernetes, przekierowują dane wyjściowe z stdout i stderr do plików dziennika.
• Użyj bibliotek rejestrowania, które integrują się z usługą ILogger, takich jak Serilog i NLog.
• Użyj dostawców logowania dla OTel, takich jak OTLP. Sekcja kodu odpowiedzialna za rejestrowanie w kroku 5 dodaje dostawcę OTel.

Na pulpicie dzienniki są wyświetlane jako dzienniki ustrukturyzowane. Wszystkie właściwości ustawione w komunikacie dziennika stają się polami w rekordzie dziennika.

9.2 Widok metryk

Na Aspire pulpicie nawigacyjnym są wyświetlane metryki dla poszczególnych zasobów. Zasób to termin OTel oznaczający źródło telemetrii, na przykład proces. Po wybraniu zasobu pulpit nawigacyjny wyświetla każdą metrykę, którą zasób został wysłany do punktu końcowego OTLP. Lista metryk jest dynamiczna i aktualizuje się, gdy pulpit nawigacyjny otrzymuje nowe metryki.

Widok metryk zależy od typu używanej metryki:

• Panel pokazuje liczniki bezpośrednio.
• W przypadku histogramów, które rejestrują wartość dla każdego żądania, taką jak czas trwania lub liczba bajtów wysłanych na żądanie, panel zbiera wartości w serię przedziałów i przedstawia na wykresie percentyle P50, P90 i P99. Wyniki histogramu mogą zawierać przykładowe punkty danych wraz z identyfikatorem śledzenia/zakresu dla tego żądania. Pulpit nawigacyjny przedstawia je jako kropki na grafie. Wybierz jeden, aby przejść do odpowiedniego śladu, aby zobaczyć, co spowodowało tę wartość. Ta funkcja ułatwia diagnozowanie wartości odstających.
• Metryki mogą zawierać wymiary, które są parami klucz/wartość skojarzonymi z poszczególnymi wartościami. Panel agreguje wartości według wymiaru. Użyj list rozwijanych w widoku, aby filtrować wyniki według określonych wymiarów, na przykład tylko żądań GET lub konkretnej trasy URL w ASP.NET.

9.3 Widok śledzenia

W widoku śledzenia są wyświetlane ślady. Każdy ślad jest zestawem działań, które mają ten sam identyfikator śledzenia. Obejmuje śledzenie pracy, a każdy zakres reprezentuje jednostkę pracy. Przetwarzanie żądania ASP.NET powoduje utworzenie odcinka czasowego. Tworzenie żądania HttpClient jest czasem trwania operacji. Śledząc element nadrzędny każdego spanu, tworzysz hierarchię spanów, którą możesz zwizualizować. Podczas zbierania zakresów z każdego zasobu (procesu) można śledzić pracę w ramach serii usług. Żądania HTTP zawierają nagłówek przekazujący identyfikator śladu i identyfikator nadrzędnego spanu do następnej usługi. Każdy zasób musi zbierać dane telemetryczne i wysyłać je do tego samego modułu zbierającego, który następnie agreguje i przedstawia hierarchię zakresów.

Na pulpicie nawigacyjnym jest wyświetlana lista śladów z informacjami podsumowującymi. Za każdym razem, gdy pulpit nawigacyjny wykryje zakresy z nowym identyfikatorem śledzenia, dodaje wiersz do tabeli. Wybierz pozycję Widok , aby wyświetlić wszystkie zakresy w śladzie.

Wybierz span, aby wyświetlić jego szczegóły, w tym wszelkie jego właściwości, takie jak tag greeting, ustawiony w kroku 7.