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

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

Kromě toho, že je standardní součástí rozhraní .NET Aspire, je řídicí panel Aspire k dispozici jako samostatný kontejner Dockeru, který poskytuje koncový bod OTLP, na který lze odesílat telemetrii, 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 určen jako vývojářský vizualizační nástroj, nikoli pro monitorování v produkčním prostředí.

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

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

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

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>

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ů nástrojů a našeho vlastního zdroje aktivit.

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

Je možné nakonfigurovat vývozce OTLP pomocí rozhraní API v kódu, ale častěji se konfiguruje 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é OTel proměnné, například OTEL_RESOURCE_ATTRIBUTES, k definování atributů prostředků.

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.

[]

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

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ů.

Protokolovací příkazy z kódu se výstupně zobrazují 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 lze logy exportovat z .NET:

• stdout a stderr výstup je přesměrován do souborů protokolů systémů 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. Sekce protokolování v rámci 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.

Ří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.

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

• Čítače se zobrazí přímo.
• Histogramy, které sledují hodnotu za požadavek, jako je časový úsek nebo bajty odeslané za požadavek, se shromažďují do řady kategorií. Řídicí panel bude grafovat percentily P50, P90 a P99. Výsledky histogramu mohou zahrnovat exempláře, což jsou jednotlivé datové body spolu s trasou/spanId pro daný požadavek. Zobrazí se jako tečky v grafu. Výběrem jedné z možností se dostanete na příslušnou stopu, abyste mohli zjistit, co způsobilo tuto hodnotu. 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 seznamů v zobrazení můžete výsledky filtrovat tak, abyste mohli zobrazit konkrétní dimenze, například pouze GET požadavky, nebo konkrétní trasu URL adresy v ASP.NET.

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 pomocí úseků, které představují jednotku práce. Zpracování požadavku ASP.NET vytvoří span. Vytvoření požadavku HttpClient bude časový úsek. Tím, že sledujeme nadřazenou oblast, můžeme vizualizovat hierarchii oblastí. 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ý zdroj musí shromažďovat telemetrii a posílat ji do stejného kolektoru. Potom agreguje a prezentuje hierarchii rozsahů.

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

Výběrem rozsahu se zobrazí jeho podrobnosti včetně jakýchkoli vlastností rozsahu, jako značka greeting, kterou jsme nastavili v kroku 3.