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

Tento článek je jednou z řady příkladů, která ilustruje pozorovatelnost technologie .NET pomocí OpenTelemetry.

Kromě toho, že je standardní součástí Aspire, je Aspire Dashboard k dispozici jako samostatný Docker kontejner, který poskytuje OTLP koncový bod, na který lze odesílat telemetrii. Řídicí panel vizualizuje protokoly, metriky a trasování. Použití řídicího panelu tímto způsobem není závislé na Aspire, a vizualizuje telemetrii z jakékoli aplikace, která odesílá telemetrii prostřednictvím OTLP. Funguje stejně dobře pro aplikace napsané v Javě, GoLangu nebo Pythonu za předpokladu, že můžou odesílat telemetrii do koncového bodu OTLP.

Použití řídicího panelu Aspire má méně kroků konfigurace a nastavení než použití opensourcových řešení, jako jsou Prometheus, Grafana a Jaeger. Na rozdíl od těchto nástrojů Aspire je ale řídicí panel určený jako vývojářský vizualizační nástroj, nikoli 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í kód 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á zprostředkovatele OTel do ILoggeru, aby shromažďoval 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.

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

Exportér OTLP je možné nakonfigurovat prostřednictvím rozhraní API v kódu, ale je běžnější ho nakonfigurovat 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ů.

Poznámka:

Častou chybou je zaměnit AppSettings.json a AppSettings.Development.json. Pokud je tato možnost k dispozici, použije se při F5 ze sady Visual Studio a všechna nastavení v AppSettings.json budou ignorována.

7. Spusťte kontejner Aspire řídicího panelu

Použijte docker ke stažení a spuštění kontejneru dashboardu.

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 s localhost, například http://localhost:18888/login?t=123456780abcdef123456780, a otevřete ji v prohlížeči. Nebo můžete klíč vložit i po zobrazení dialogového okna pro přihlášení, když je /login?t= zobrazeno. 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

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 protokoly exportovat z .NET:

• stdout a stderr výstup je přesměrován do souborů protokolů systémů kontejnerů, jako je Kubernetes.
• Použití knihoven protokolování, které se integrují s ILoggerem Mezi tyto knihovny patří Serilog a 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.

8.2 Zobrazení metrik

Řídicí Aspire panel zobrazuje metriky podle jednotlivých prostředků (prostředek je v OTel způsob, jak označit zdroje telemetrie, jako je proces). Když vyberete prostředek, řídicí panel vyčíslí každou metriku, která byla odeslána do koncového bodu OTLP prostředkem. Seznam metrik je dynamický a aktualizuje se při přijetí nových metrik.

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

• Čítače se zobrazují 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 grafuje 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. Zobrazují se jako tečky v grafu. Výběrem se přenesete na příslušnou stopu, abyste viděli, co způsobilo tuto hodnotu. To je užitečné pro diagnostiku odlehlých bodů.
• 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 vyfiltrovat a podívat se na konkrétní dimenze, jako jsou jenom GET požadavky, nebo ty, které se týkají konkrétní trasy URL v ASP.NET.

8.3 Zobrazení trasování

Pohled na trasování zobrazuje seznam tras. Každé sledování je soubor aktivit, které sdílejí stejné traceId. Práce se sleduje pomocí úseků, které představují pracovní jednotku. Zpracování požadavku ASP.NET vytvoří span. Vytvoření požadavku HttpClient je ú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) můžete sledovat 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 zobrazuje seznam trasování se souhrnnými informacemi. Kdykoli se zobrazí úsek s novým traceId, získá vlastní řádek v tabulce. Kliknutím na tlačítko Zobrazit zobrazíte všechny rozsahy v trasování.

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