Dela via

Exempel: Använd OpenTelemetry med OTLP och den fristående Aspire-instrumentpanelen

  • Artikel

Det här är ett av flera exempel som illustrerar .NET-observerbarhet med OpenTelemetry.

Förutom att vara en standarddel av .NET Aspire är Aspire-instrumentpanelen tillgänglig som en fristående dockercontainer, som tillhandahåller en OTLP-slutpunktstelemetri kan skickas till, och den visualiserar loggar, mått och spårningar. Om du använder instrumentpanelen på det här sättet är det inte beroende av .NET Aspire, utan visualiserar telemetri från alla program som skickar telemetri via OTLP. Det fungerar lika bra för program som skrivits i Java, GoLang, Python osv. förutsatt att de kan skicka sin telemetri till en OTLP-slutpunkt.

Att använda Aspire-instrumentpanelen har mindre konfigurations- och konfigurationssteg än att använda lösningar med öppen källkod, till exempel Prometheus, Grafana och Jaeger, men till skillnad från dessa verktyg är Aspire-instrumentpanelen avsedd som ett visualiseringsverktyg för utvecklare och inte för produktionsövervakning.

1. Skapa projektet

Skapa ett enkelt webb-API-projekt med hjälp av mallen ASP.NET Core Empty i Visual Studio eller följande .NET CLI-kommando:

dotnet new web

2. Lägg till mått och aktivitetsdefinitioner

Följande kod definierar ett nytt mått (greetings.count) för hur många gånger API:et har anropats och en ny aktivitetskälla (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. Skapa en API-slutpunkt

Infoga följande mellan builder.Build(); och app.Run()

app.MapGet("/", SendGreeting);

Infoga följande funktion längst ned i filen:

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

Kommentar

Slutpunktsdefinitionen använder inte något specifikt för OpenTelemetry. Den använder .NET-API:erna för observerbarhet.

4. Referera till OpenTelemetry-paketen

Använd NuGet Package Manager eller kommandoraden för att lägga till följande NuGet-paket:

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

Kommentar

Använd de senaste versionerna eftersom OTel-API:erna ständigt utvecklas.

5. Konfigurera OpenTelemetry med rätt leverantörer

Infoga följande kod före 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();
}

Den här koden konfigurerar OpenTelemetry med de olika telemetrikällorna:

  • Den lägger till en OTel-provider till ILogger för att samla in loggposter.
  • Den konfigurerar mått, registrerar instrumentationsprovidrar och mätare för ASP.NET och vår anpassade mätare.
  • Den konfigurerar spårning, registrering av instrumentationsproviders och vår anpassade ActivitySource.

Därefter registreras OTLP-exportören med hjälp av env vars för konfigurationen.

6. Konfigurera OTLP-miljövariabler

OTLP-exportören kan konfigureras via API:er i kod, men det är vanligare att konfigurera den via miljövariabler. Lägg till följande i AppSettings.Development.json

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

Du kan lägga till ytterligare miljövariabler för .NET OTLP-exportören eller vanliga OTel-variabler, till exempel OTEL_RESOURCE_ATTRIBUTES för att definiera resursattribut.

Kommentar

En vanlig gotcha är att blanda AppSettings.json och AppSettings.Development.json, om det senare finns används det när du F5 från Visual Studio och alla inställningar i AppSettings.json ignoreras.

7. Starta containern Aspire Dashboard

Använd docker för att ladda ned och köra instrumentpanelscontainern.

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

Data som visas på instrumentpanelen kan vara känsliga. Som standard skyddas instrumentpanelen med autentisering som kräver en token för inloggning. Token visas i resultatet när containern körs.

[Aspire-instrumentpanel]

Kopiera url:en som visas och ersätt 0.0.0.0 med localhost, t.ex http://localhost:18888/login?t=123456780abcdef123456780 . och öppna den i webbläsaren, eller så kan du även klistra in nyckeln efter /login?t= när inloggningsdialogrutan visas. Token ändras varje gång du startar containern.

8. Kör projektet

Kör projektet och få sedan åtkomst till API:et med webbläsaren eller curl.

curl -k http://localhost:7275

Varje gång du begär sidan ökar antalet hälsningar som har gjorts.

8.1 Loggutdata

Loggningsinstruktionerna från koden matas ut med .ILogger Som standard är konsolprovidern aktiverad så att utdata dirigeras till konsolen.

Det finns ett par alternativ för hur loggar kan tas ut från .NET:

  • stdout och stderr utdata omdirigeras till loggfiler av containersystem som Kubernetes.
  • Med hjälp av loggningsbibliotek som ska integreras med ILogger inkluderar dessa Serilog eller NLog.
  • Använda loggningsprovidrar för OTel, till exempel OTLP. Loggningsavsnittet i koden från steg 5 lägger till OTel-providern.

Loggarna visas på instrumentpanelen som strukturerade loggar – alla egenskaper som du anger i loggmeddelandet extraheras som fält i loggposten.

Loggar i fristående instrumentpanel

8.2 Visa måtten

Instrumentpanelen Aspire visar mått per resurs (en resurs är OTel-sättet att tala om telemetrikällor, till exempel en process). När en resurs har valts räknar instrumentpanelen upp varje mått som har skickats till dess OTLP-slutpunkt av resursen. Listan över mått är dynamisk och uppdateras när nya mått tas emot.

Mått på fristående instrumentpanel

Vyn för måtten beror på vilken typ av mått som används:

  • Räknare visas direkt.
  • Histogram som spårar ett värde per begäran, till exempel ett tidsintervall eller byte som skickas per begäran, samlas in i en serie bucketar. Instrumentpanelen visar P50-, P90- och P99-percentilerna. Histogramresultat kan innehålla exempel, som är enskilda datapunkter tillsammans med trace/spanId för den begäran. Dessa visas som punkter i diagrammet. Om du väljer en navigerar du till respektive spårning så att du kan se vad som hände för att orsaka det värdet. Detta är användbart för att diagnostisera avvikande värden.
  • Mått kan innehålla dimensioner, som är nyckel/värde-par som är associerade med enskilda värden. Värdena aggregeras per dimension. Med hjälp av listrutorna i vyn kan du filtrera resultaten för att titta på specifika dimensioner, till exempel endast GET begäranden eller de för en specifik URL-väg i ASP.NET.

8.3 Visa spårningen

Spårningsvyn visar en lista över spårningar – varje spårning är en uppsättning aktiviteter som delar samma traceId. Arbetet spåras med intervall som representerar en arbetsenhet. Bearbetning av en ASP.NET begäran skapar ett spann. Att göra en HttpClient-begäran är ett intervall. Genom att spåra intervallets överordnade kan en hierarki med intervall visualiseras. Genom att samla in intervall från varje resurs (process) spårar vi det arbete som sker i en serie tjänster. Http-begäranden har en rubrik som används för att skicka traceId och överordnat spanId till nästa tjänst. Varje resurs måste samla in telemetri och skicka den till samma insamlare. Sedan aggregeras och presenteras en hierarki med intervallen.

Spårningar på fristående instrumentpanel

Instrumentpanelen visar en lista över spårningar med sammanfattningsinformation. När intervall med ett nytt traceId visas får de en rad i tabellen. Om du klickar på vyn visas alla intervall i spårningen.

Sträcker sig över fristående instrumentpanel

Om du väljer ett intervall visas dess information, inklusive eventuella egenskaper för intervallet, till exempel taggen greeting vi angav i steg 3.