Sdílet prostřednictvím

Příklad: Použití OpenTelemetry s OTLP a samostatným řídicím panelem Aspire

  • Článek

Toto je jedna z řady příkladů, která ilustruje pozorovatelnost .NET pomocí OpenTelemetry.

Kromě standardní části rozhraní .NET Aspire je řídicí panel Aspire k dispozici jako samostatný kontejner Dockeru, který poskytuje telemetrii koncového bodu OTLP, do které se dá odesílat, a vizualizuje protokoly, metriky a trasování. Použití řídicího panelu tímto způsobem nemá žádnou závislost na rozhraní .NET Aspire, bude vizualizovat telemetrii z jakékoli aplikace, která odesílá telemetrii prostřednictvím OTLP. Funguje stejně dobře pro aplikace napsané v Javě, GoLangu, Pythonu atd. za předpokladu, že může odesílat telemetrii do koncového bodu OTLP.

Použití řídicího panelu Aspire má méně konfigurace a nastavení než použití opensourcových řešení, jako jsou Prometheus, Grafana a Jaeger, ale na rozdíl od těchto nástrojů je řídicí panel Aspire zamýšlený jako vývojářský vizualizační nástroj, a ne pro produkční monitorování.

1. Vytvoření projektu

Vytvořte jednoduchý projekt webového rozhraní API pomocí šablony ASP.NET Core Empty v sadě Visual Studio nebo pomocí následujícího příkazu .NET CLI:

dotnet new web

2. Přidání metrik a definic aktivit

Následující kód definuje novou metriku (greetings.count) pro počet volání rozhraní API a nový zdroj aktivity (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. Vytvoření koncového bodu rozhraní API

Vložte následující položky mezi builder.Build(); a app.Run()

app.MapGet("/", SendGreeting);

Do dolní části souboru vložte následující funkci:

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!";
}

Poznámka:

Definice koncového bodu nepoužívá nic specifického pro OpenTelemetry. K pozorovatelnosti používá rozhraní .NET API.

4. Odkaz na balíčky OpenTelemetry

Pomocí Správce balíčků NuGetu nebo příkazového řádku přidejte následující balíčky 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>

Poznámka:

Používejte nejnovější verze, protože se rozhraní API OTel neustále vyvíjejí.

5. Konfigurace OpenTelemetry se správnými poskytovateli

Před vložte následující kód 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();
}

Tento kód nastaví OpenTelemetry s různými zdroji telemetrie:

  • Přidá do ILoggeru zprostředkovatele OTel, který shromažďuje záznamy protokolu.
  • Nastavuje metriky, registruje poskytovatele instrumentace a měřiče pro ASP.NET a vlastní měřič.
  • Nastaví trasování, registraci poskytovatelů instrumentace a vlastního zdroje aktivit.

Pak zaregistruje vývozce OTLP pomocí env vars pro svou konfiguraci.

6. Konfigurace proměnných prostředí OTLP

Vývozce OTLP je možné nakonfigurovat prostřednictvím rozhraní API v kódu, ale jeho častější konfigurace prostřednictvím proměnných prostředí. Do AppSettings.Development.json přidejte následující :

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

Můžete přidat další proměnné prostředí pro exportér .NET OTLP nebo běžné proměnné OTel, například OTEL_RESOURCE_ATTRIBUTES definovat atributy prostředků.

Poznámka:

Běžnou sadou je kombinovat AppSettings.json a AppSettings.Development.json, pokud je k dispozici, použije se při F5 ze sady Visual Studio a všechna nastavení v AppSettings.json budou ignorována.

7. Spuštění kontejneru řídicího panelu Aspire

Pomocí Dockeru stáhněte a spusťte kontejner řídicího panelu.

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

Data zobrazená na řídicím panelu můžou být citlivá. Řídicí panel je ve výchozím nastavení zabezpečený pomocí ověřování, které vyžaduje token pro přihlášení. Token se zobrazí ve výsledném výstupu při spuštění kontejneru.

[Aspire Dashboard]

Zkopírujte zobrazenou adresu URL a nahraďte 0.0.0.0 ji , localhostnapř http://localhost:18888/login?t=123456780abcdef123456780 a otevřete ji v prohlížeči, nebo můžete klíč vložit také po /login?t= zobrazení přihlašovacího dialogového okna. Token se změní při každém spuštění kontejneru.

8. Spusťte projekt.

Spusťte projekt a pak přejděte k rozhraní API pomocí prohlížeče nebo curl.

curl -k http://localhost:7275

Pokaždé, když požádáte o stránku, zvýší se počet provedených pozdravů.

8.1 Výstup protokolu

Příkazy protokolování z kódu jsou výstupem pomocí ILogger. Ve výchozím nastavení je poskytovatel konzoly povolený, aby se výstup směroval do konzoly.

Existuje několik možností, jak se protokoly dají výchozí přenos dat z .NET:

  • stdout a stderr výstup se přesměruje na soubory protokolů systémy kontejnerů, jako je Kubernetes.
  • Mezi knihovny protokolování, které se budou integrovat s ILoggerem, patří Serilog nebo NLog.
  • Použití zprostředkovatelů protokolování pro OTel, jako je OTLP. Oddíl protokolování v kódu z kroku 5 přidá zprostředkovatele OTel.

Protokoly se zobrazují na řídicím panelu jako strukturované protokoly – všechny vlastnosti nastavené ve zprávě protokolu se extrahují jako pole v záznamu protokolu.

Protokoly na samostatném řídicím panelu

8.2 Zobrazení metrik

Řídicí panel Aspire zobrazuje metriky na základě jednotlivých prostředků (prostředek, který představuje způsob, jak mluvit o zdrojích telemetrie, jako je proces). Když vyberete prostředek, řídicí panel vypíše každou metriku, která byla odeslána do koncového bodu OTLP prostředkem. Seznam metrik je dynamický a při přijetí nových metrik se aktualizuje.

Metriky na samostatném řídicím panelu

Zobrazení metrik bude záviset na typu použité metriky:

  • Čítače se zobrazí přímo.
  • Histogramy, které sledují hodnotu na požadavek, jako je časový rozsah nebo bajty odeslané na požadavek, se shromažďují do řady kbelíků. Řídicí panel bude grafovat percentily P50, P90 a P99. Výsledky histogramu můžou zahrnovat příklady, což jsou jednotlivé datové body společně s trasovací/spanId pro daný požadavek. Zobrazí se jako tečky v grafu. Když vyberete jednu, přejdete na příslušné trasování, abyste viděli, co se stalo, že tato hodnota způsobila. To je užitečné pro diagnostiku odlehlých hodnot.
  • Metriky můžou zahrnovat dimenze, což jsou páry klíč/hodnota přidružené k jednotlivým hodnotám. Hodnoty se agregují na dimenzi. Pomocí rozevíracích seznamu v zobrazení můžete výsledky filtrovat tak, aby se podívaly na konkrétní dimenze, jako jsou pouze GET požadavky, nebo na konkrétní trasu URL v ASP.NET.

8.3 Zobrazení trasování

V zobrazení trasování se zobrazí seznam trasování – každé trasování je sada aktivit, které sdílejí stejné id trasování. Práce se sleduje s rozsahy, které představují jednotku práce. Zpracování požadavku ASP.NET vytvoří rozsah. Vytvoření požadavku HttpClient bude rozsah. Sledováním nadřazeného rozsahu je možné vizualizovat hierarchii rozsahů. Shromažďováním rozsahů z každého prostředku (procesu) sledujeme práci, která se děje napříč řadou služeb. Požadavky HTTP mají hlavičku, která se používá k předání traceId a nadřazeného spanId další službě. Každý prostředek musí shromažďovat telemetrii a posílat je do stejného kolektoru. Potom agreguje a prezentuje hierarchii rozsahů.

Trasování na samostatném řídicím panelu

Řídicí panel zobrazí seznam trasování se souhrnnými informacemi. Kdykoli se zobrazí rozsah s novým identifikátorem traceId, zobrazí se v tabulce řádek. Kliknutím na zobrazení se zobrazí všechna rozsahy v trasování.

Rozsahy na samostatném řídicím panelu

Výběrem rozsahu se zobrazí její podrobnosti včetně všech vlastností v rozsahu, jako greeting je značka, která jsme nastavili v kroku 3.