Använd OpenTelemetry med OTLP och Aspire-instrumentpanelen

Den här artikeln visar hur du instrumentar ett .NET webb-API med OpenTelemetry och skickar loggar, mått och spårningar till Aspire instrumentpanelen med hjälp av OTLP. Du lägger till OpenTelemetry-paketen, konfigurerar anpassade mått och spårningar och visar resultatet på instrumentpanelen.

Instrumentpanelen Aspire är en standarddel av Aspire, men den är också tillgänglig som en fristående Docker-container som tillhandahåller en OTLP-slutpunkt för att skicka telemetri. Instrumentpanelen visualiserar loggar, mått och spårningar. Att använda instrumentpanelen på det här sättet är inte beroende av Aspire, och den visualiserar telemetri från valfri app som skickar telemetri via OTLP. Det fungerar lika bra för appar som skrivits i Java, Go eller Python, förutsatt att de kan skicka sin telemetri till en OTLP-slutpunkt.

Instrumentpanelen Aspire kräver mindre konfiguration och färre installationssteg än lösningar med öppen källkod, till exempel Prometheus, Grafana och Jaeger. Men till skillnad från dessa verktyg Aspire är instrumentpanelen ett visualiseringsverktyg för utvecklare, inte ett produktionsövervakningsverktyg.

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. Referera till OpenTelemetry-paketen

Om du vill lägga till OpenTelemetry-paketen använder du NuGet-Správca balíkov eller kör följande dotnet add package kommandon:

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

Du kan också lägga till följande PackageReference objekt direkt i projektfilen:

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

Anteckning

Eftersom OTel-API:erna ständigt utvecklas använder du de senaste versionerna.

3. Lägg till användningsdirektiv

Lägg till följande using direktiv överst i filen:

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

4. Lägg till mått och aktivitetsdefinitioner

Följande kod definierar ett nytt mått (greetings.count) som räknar hur många gånger en klient anropar API:et och en ny aktivitetskälla (Otel.Example). Infoga den här koden före 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. Konfigurera OpenTelemetry med rätt leverantörer

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

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 den anpassade mätaren.
• Den ställer in spårning, registrerar instrumenteringsleverantörer och den anpassade ActivitySource.

Därefter registreras OTLP-exportören med hjälp av miljövariabler för konfiguration.

6. Konfigurera OTLP-inställningar

Du kan konfigurera OTLP-exportören via API:er i kod, miljövariabler eller programkonfiguration. I det här exemplet lägger du till OTLP-inställningarna i roten av appsettings.Development.json, efter avsnittet Logging :

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

Lägg till andra inställningar för .NET OTLP-exportör eller vanliga OTel-inställningar, till exempel OTEL_RESOURCE_ATTRIBUTES för att definiera resursattribut.

Anteckning

ASP.NET Core läser in både appsettings.json och appsettings.Development.json. Inställningar i appsettings.Development.json åsidosätter duplicerade inställningar i appsettings.json när du kör appen i utvecklingsmiljön.

7. Skapa en API-slutpunkt

Infoga följande kod 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!";
}

Anteckning

Slutpunktsdefinitionen använder inget specifikt för OpenTelemetry. Den använder .NET-API:erna för observerbarhet.

8. Starta containern AspireInstrumentpanel

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. Instrumentpanelen kräver som standard en autentiseringstoken för att logga in. Containern visar denna token i sina utdata.

Kopiera URL:en, ersätt 0.0.0.0 med localhost, till exempel http://localhost:18888/login?t=123456780abcdef123456780, och öppna den i webbläsaren. Eller klistra in nyckeln efter /login?t= i inloggningsdialogrutan. Token ändras varje gång du startar containern.

9. Kör projektet

Kör projektet med dotnet run. Konsolens utdata visar url:erna som appen lyssnar på, till exempel:

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

Använd porten som visas i dina egna konsolutdata eftersom den kan skilja sig från exemplen i den här artikeln. Använd en webbläsare eller curl för att komma åt API:et på den porten:

curl -k http://localhost:5086

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

9.1 Loggutdata

Koden loggar instruktioner med hjälp av ILogger. Som standard aktiverar .NET konsolprovidern, som dirigerar utdata till konsolen.

Du kan exportera loggar från .NET på några sätt:

• Containersystem såsom Kubernetes omdirigerar stdout och stderr utdata till loggfiler.
• Använd loggningsbibliotek som integreras med ILogger, till exempel Serilog och NLog.
• Använd loggningsproviders för OTel, till exempel OTLP. Loggningsavsnittet i koden i steg 5 lägger till OTel-providern.

Instrumentpanelen visar loggar som strukturerade loggar. Alla egenskaper som du anger i loggmeddelandet blir fält i loggposten.

9.2 Mätvärdesvy

Instrumentpanelen Aspire visar mått per resurs. En resurs är OTel-termen för en telemetrikälla, till exempel en process. När du väljer en resurs visar instrumentpanelen varje mått som resursen skickade till sin OTLP-slutpunkt. Listan över mått är dynamisk och uppdateras när instrumentpanelen tar emot nya mått.

Måttvyn beror på vilken typ av mått du använder:

• Instrumentpanelen visar räknare direkt.
• För histogram som spårar ett värde för varje begäran, till exempel ett tidsintervall eller antal byte som skickas för varje begäran, samlar instrumentpanelen in värden i en serie intervall och visar percentilerna P50, P90 och P99 i ett diagram. Resultat för histogram kan innehålla exemplar, det vill säga enskilda datapunkter tillsammans med spårnings-/spann-ID för den förfrågan. Instrumentpanelen visar dessa som punkter i diagrammet. Välj en för att navigera till respektive spårning så att du kan se vad som orsakade det värdet. Den här funktionen hjälper dig att diagnostisera avvikande värden.
• Mått kan innehålla dimensioner, som är nyckel/värde-par som är associerade med enskilda värden. Instrumentpanelen aggregerar värden per dimension. Använd listrutorna i vyn för att filtrera resultat efter specifika dimensioner, till exempel GET endast begäranden eller en specifik URL-väg i ASP.NET.

9.3 Spårningsvy

Spårningsvyn visar spår. Varje spårning är en uppsättning aktiviteter som delar samma spårnings-ID. Spann spårar arbete, och varje spann 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 varje spanns överordnade kan du skapa en hierarki med intervall som du kan visualisera. När du samlar in intervall från varje resurs (process) kan du spåra arbete i en serie tjänster. HTTP-begäranden innehåller en header som vidarebefordrar spår-ID:t och det överordnade span-ID:t till nästa tjänst. Varje resurs måste samla in telemetri och skicka den till samma insamlare, som sedan aggregerar och visar en hierarki med spann.

Instrumentpanelen visar en lista med spårningar med sammanfattningsinformation. När instrumentpanelen identifierar intervall med ett nytt spårnings-ID lägger den till en rad i tabellen. Välj Visa för att visa alla intervall i spårningen.

Välj ett intervall för att visa dess information, inklusive eventuella egenskaper för intervallet, till exempel taggen greeting du angav i steg 7.