OpenTelemetry gebruiken met OTLP en het Aspire dashboard

In dit artikel leest u hoe u een .NET web-API met OpenTelemetry instrumenteert en de logboeken, metrische gegevens en traceringen naar het Aspire dashboard verzendt met behulp van OTLP. U voegt de OpenTelemetry-pakketten toe, configureert aangepaste metrische gegevens en traceringen en bekijkt de resultaten in het dashboard.

Het Aspire dashboard is een standaardonderdeel van Aspire, maar het is ook beschikbaar als een zelfstandige Docker-container die een OTLP-eindpunt biedt voor het verzenden van telemetrie. Het dashboard visualiseert logboeken, metrische gegevens en traceringen. Het gebruik van het dashboard op deze manier heeft geen afhankelijkheid Aspireen visualiseert telemetrie van elke app die telemetrie verzendt met behulp van OTLP. Het werkt even goed voor apps die zijn geschreven in Java, Go of Python, mits ze hun telemetrie naar een OTLP-eindpunt kunnen verzenden.

Het Aspire dashboard vereist minder configuratie en minder installatiestappen dan opensource-oplossingen zoals Prometheus, Grafana en Jaeger. Maar in tegenstelling tot deze hulpprogramma's is het Aspire dashboard een hulpprogramma voor visualisatie van ontwikkelaars, niet een hulpprogramma voor productiebewaking.

1. Het project maken

Maak een eenvoudig web-API-project met behulp van de ASP.NET Core Empty-sjabloon in Visual Studio of de volgende .NET CLI-opdracht:

dotnet new web

2. Verwijzen naar de OpenTelemetry-pakketten

Als u de OpenTelemetry-pakketten wilt toevoegen, gebruikt u de NuGet-Pakketbeheer of voert u de volgende dotnet add package opdrachten uit:

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

U kunt ook de volgende PackageReference items rechtstreeks toevoegen aan het projectbestand:

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

3. Toevoegen met behulp van instructies

Voeg de volgende using instructies toe aan het begin van het bestand:

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

4. Metrische gegevens en activiteitsdefinities toevoegen

De volgende code definieert een nieuwe metrische waarde (greetings.count) waarmee wordt geteld hoe vaak een client de API aanroept en een nieuwe activiteitsbron (Otel.Example). Voeg deze code in vóór 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. OpenTelemetry configureren met de juiste providers

Voeg de volgende code in voor 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);
});

Met deze code stelt u OpenTelemetry in met de verschillende telemetriebronnen:

• Het voegt een OTel-provider toe aan ILogger om logrecords te verzamelen.
• Het stelt metrische gegevens in, registreert instrumentatieproviders en meters voor ASP.NET en de aangepaste meter.
• Het stelt tracering in, registreert instrumentatieproviders en de aangepaste ActivitySource.

Vervolgens wordt de OTLP-exporteur geregistreerd met behulp van omgevingsvariabelen voor de configuratie.

6. OTLP-instellingen configureren

U kunt de OTLP-exporteur configureren via API's in code, omgevingsvariabelen of toepassingsconfiguratie. Voeg voor dit voorbeeld de OTLP-instellingen op rootniveau in appsettings.Development.json toe, na de sectie Logging:

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

Voeg andere instellingen toe voor de .NET OTLP-exporteur of algemene OTel-instellingen, zoals OTEL_RESOURCE_ATTRIBUTES het definiëren van resourcekenmerken.

7. Een API-eindpunt maken

Voeg de volgende code in tussen builder.Build en app.Run():

app.MapGet("/", SendGreeting);

Voeg de volgende functie onder aan het bestand in:

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

8. Start de Aspire Dashboard-container

Gebruik docker dit om de dashboardcontainer te downloaden en uit te voeren.

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

Gegevens die in het dashboard worden weergegeven, kunnen gevoelig zijn. Standaard is voor het dashboard een verificatietoken vereist om u aan te melden. De container geeft dit token weer in de uitvoer.

Kopieer de URL, vervang 0.0.0.0 door localhost, bijvoorbeeld http://localhost:18888/login?t=123456780abcdef123456780, en open deze in uw browser. Of plak de sleutel na /login?t= in het aanmeldingsdialoogvenster. Het token wordt telkens gewijzigd wanneer u de container start.

9. Het project uitvoeren

Voer het project uit met dotnet run. In de console-uitvoer worden de URL's weergegeven waarop de app luistert, bijvoorbeeld:

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

Gebruik de poort die wordt weergegeven in de uitvoer van uw eigen console, omdat deze mogelijk verschilt van de voorbeelden in dit artikel. Gebruik een browser of curl om toegang te krijgen tot de API op die poort:

curl -k http://localhost:5086

Telkens wanneer u de pagina aanvraagt, neemt het aantal begroetingen toe.

9.1 Logboekuitvoer

De code registreert instructies met behulp van ILogger. Standaard schakelt .NET de consoleprovider in, waarmee de uitvoer naar de console wordt omgeslagen.

U kunt logboeken op verschillende manieren vanuit .NET uitvoeren:

• Containersystemen zoals Kubernetes omleiden stdout en stderr uitvoer naar logboekbestanden.
• Gebruik logboekregistratiebibliotheken die kunnen worden geïntegreerd met ILogger, zoals Serilog en NLog.
• Gebruik logboekregistratieproviders voor OTel, zoals OTLP. De sectie voor logboekregistratie van de code in stap 5 voegt de OTel-provider toe.

Het dashboard toont logboeken als gestructureerde logboeken. Alle eigenschappen die u in het logboekbericht instelt, worden velden in de logboekrecord.

9.2 Weergave met metrische gegevens

In Aspire het dashboard worden metrische gegevens per resource weergegeven. Een resource is de OTel-term voor een bron van telemetrie, zoals een proces. Wanneer u een resource selecteert, worden in het dashboard alle metrische gegevens weergegeven die de resource naar het OTLP-eindpunt heeft verzonden. De lijst met metrische gegevens is dynamisch en wordt bijgewerkt naarmate het dashboard nieuwe metrische gegevens ontvangt.

De weergave metrische gegevens is afhankelijk van het type metrische gegevens dat u gebruikt:

• In het dashboard worden tellers rechtstreeks weergegeven.
• Voor histogrammen die een waarde per aanvraag bijhouden, zoals een periode of bytes die per aanvraag worden verzonden, verzamelt het dashboard waarden in een reeks buckets en grafieken met de percentielen P50, P90 en P99. Histogramresultaten kunnen exemplars bevatten: individuele datapunten samen met de trace-/span-ID van dat verzoek. Het dashboard toont deze als puntjes in de grafiek. Selecteer er een om naar de betreffende trace te navigeren, zodat u kunt zien wat de oorzaak van die waarde is. Met deze functie kunt u uitbijters diagnosticeren.
• Metrische gegevens kunnen dimensies bevatten, die sleutel-waardeparen zijn die zijn gekoppeld aan afzonderlijke waarden. Het dashboard voegt waarden per dimensie samen. Gebruik de vervolgkeuzelijsten in de weergave om resultaten te filteren op specifieke dimensies, zoals GET alleen aanvragen of een specifieke URL-route in ASP.NET.

9.3 Traceringsweergave

De traceringsweergave bevat traceringen. Elke tracering is een set activiteiten die dezelfde tracerings-id delen. Spans houden werk bij, en elke span vertegenwoordigt een werkeenheid. Het verwerken van een ASP.NET-aanvraag creëert een span. Het indienen van een HttpClient-aanvraag is een periode. Door van elke span de bovenliggende span bij te houden, bouwt u een hiërarchie van spans op die u kunt visualiseren. Wanneer u spans uit elke resource (proces) verzamelt, kunt u werk over een reeks services heen volgen. HTTP-verzoeken bevatten een header die de trace-ID en bovenliggende span-ID doorgeeft aan de volgende service. Elke resource moet telemetrie verzamelen en verzenden naar dezelfde collector, die vervolgens een hiërarchie van de spanten samenvoegt en weergeeft.

Het dashboard bevat een lijst met traceringen met overzichtsgegevens. Wanneer het dashboard spans met een nieuwe trace-ID detecteert, voegt het een rij aan de tabel toe. Selecteer Weergave om alle spanten in de trace weer te geven.

Selecteer een bereik om de details ervan weer te geven, inclusief eventuele eigenschappen in het bereik, zoals de greeting tag die u in stap 7 hebt ingesteld.