Voorbeeld: OpenTelemetry gebruiken met OTLP en het zelfstandige Aspire-dashboard

Dit artikel is een van een reeks voorbeelden ter illustratie van .NET-waarneembaarheid met OpenTelemetry.

Naast een standaardonderdeel van Aspire is het Aspire Dashboard beschikbaar als een zelfstandige Docker-container, die een OTLP-eindpunt biedt waarnaar telemetrie kan worden verzonden. Het dashboard visualiseert de logboeken, metrische gegevens en traceringen. Het gebruik van het dashboard op deze manier heeft geen afhankelijkheid van Aspire en visualiseert telemetrie van elke toepassing die telemetrie verzendt via OTLP. Het werkt even goed voor toepassingen die zijn geschreven in Java, GoLang of Python, mits ze hun telemetrie kunnen verzenden naar een OTLP-eindpunt.

Het gebruik van het Aspire Dashboard heeft minder configuratie- en installatiestappen dan het gebruik van Open Source-oplossingen zoals Prometheus, Grafana en Jaeger. Maar in tegenstelling tot deze hulpprogramma's is het Aspire Dashboard bedoeld als een hulpprogramma voor ontwikkelaarsvisualisatie en niet 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. Metrische gegevens en activiteitsdefinities toevoegen

De volgende code definieert een nieuwe metrische waarde (greetings.count) voor het aantal keren dat de API is aangeroepen en een nieuwe activiteitsbron (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. 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!";
}

Notitie

De eindpuntdefinitie gebruikt niets specifieks voor OpenTelemetry. De .NET-API's worden gebruikt voor waarneembaarheid.

4. Verwijzen naar de OpenTelemetry-pakketten

Gebruik de NuGet-Pakketbeheer of opdrachtregel om de volgende NuGet-pakketten toe te voegen:

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

Notitie

Gebruik de nieuwste versies, omdat de OTel-API's voortdurend in ontwikkeling zijn.

5. OpenTelemetry configureren met de juiste providers

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

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

• Er wordt een OTel-provider toegevoegd aan ILogger om logboekrecords te verzamelen.
• Het stelt metrische gegevens in, registreert instrumentatieproviders en meters voor ASP.NET en onze aangepaste meter.
• Het stelt tracering in, registreert instrumentatieproviders en onze aangepaste ActivitySource.

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

6. OTLP-omgevingsvariabelen configureren

De OTLP-exporteur kan worden geconfigureerd via API's in code, maar het is gebruikelijker om deze te configureren via omgevingsvariabelen. Voeg het volgende toe aan AppSettings.Development.json

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

U kunt extra omgevingsvariabelen toevoegen voor de .NET OTLP-exporteur of algemene OTel-variabelen, zoals OTEL_RESOURCE_ATTRIBUTES het definiëren van resourcekenmerken.

Notitie

Een veelvoorkomende valkuil is om AppSettings.json en AppSettings.Development.json door elkaar te halen. Als de laatste aanwezig is, wordt deze gebruikt wanneer u F5 vanuit Visual Studio gebruikt en worden alle instellingen in AppSettings.json genegeerd.

7. 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. Het dashboard is standaard beveiligd met verificatie waarvoor een token is vereist om u aan te melden. Het token wordt weergegeven in de resulterende uitvoer bij het uitvoeren van de container.

Kopieer de weergegeven URL en vervang deze 0.0.0.0 door localhostbijvoorbeeld http://localhost:18888/login?t=123456780abcdef123456780en open deze in uw browser. Wanneer het aanmeldingsdialoogvenster wordt weergegeven, kunt u ook de sleutel plakken na /login?t=. Het token wordt telkens gewijzigd wanneer u de container start.

8. Het project uitvoeren

Voer het project uit en open vervolgens de API met de browser of curl.

curl -k http://localhost:7275

Telkens wanneer u de pagina aanvraagt, wordt het teller voor het aantal begroetingen verhoogd.

8.1 Logboekuitvoer

De logboekregistratie-instructies van de code worden uitgevoerd met behulp van ILogger. De consoleprovider is standaard ingeschakeld, zodat de uitvoer wordt omgeleid naar de console.

Er zijn enkele opties voor hoe logboeken kunnen worden verzonden vanuit .NET:

• stdout en stderr uitvoer wordt omgeleid naar logboekbestanden door containersystemen zoals Kubernetes.
• Logboekregistratiebibliotheken gebruiken die zijn geïntegreerd met ILogger. Deze bibliotheken omvatten Serilog en NLog.
• Logboekregistratieproviders gebruiken voor OTel, zoals OTLP. De sectie logboekregistratie in de code uit stap 5 voegt de OTel-provider toe.

De logboeken worden weergegeven in het dashboard als gestructureerde logboeken. Alle eigenschappen die u in het logboekbericht instelt, worden geëxtraheerd als velden in de logboekrecord.

8.2 De metrische gegevens weergeven

Het Dashboard Van Aspire toont metrische gegevens per resource (een resource die de OTel-manier is om te praten over bronnen van telemetrie, zoals een proces). Wanneer een resource is geselecteerd, bevat het dashboard elke metrische waarde die door de resource naar het OTLP-eindpunt is verzonden. De lijst met metrische gegevens is dynamisch en wordt bijgewerkt wanneer er nieuwe metrische gegevens worden ontvangen.

De weergave voor de metrische gegevens is afhankelijk van het type metrische gegevens dat wordt gebruikt:

• Tellers worden rechtstreeks weergegeven.
• Histogrammen die een waarde per aanvraag bijhouden, zoals een periode of bytes die per aanvraag worden verzonden, worden verzameld in een reeks buckets. In het dashboard worden de percentielen P50, P90 en P99 weergegeven. Histogramresultaten kunnen exemplaren bevatten, die afzonderlijke gegevenspunten zijn, samen met de tracerings-/spanId voor die aanvraag. Deze worden weergegeven als puntjes in de grafiek. Als u er een selecteert, gaat u naar de respectieve trace, zodat u kunt zien wat er is gebeurd om die waarde te veroorzaken. Dit is handig voor het diagnosticeren van uitbijters.
• Metrische gegevens kunnen dimensies bevatten, die sleutel-waardeparen zijn die zijn gekoppeld aan afzonderlijke waarden. De waarden worden geaggregeerd per dimensie. Met behulp van de vervolgkeuzelijsten in de weergave kunt u de resultaten filteren om specifieke dimensies te bekijken, zoals alleen GET aanvragen of die voor een specifieke URL-route in ASP.NET.

8.3 De tracering weergeven

In de traceringsweergave ziet u een lijst met traces. Elke trace is een set activiteiten die hetzelfde traceId delen. Werk wordt bijgehouden met spans, die een werkeenheid vertegenwoordigen. Het verwerken van een ASP.NET-aanvraag creëert een span. Het indienen van een HttpClient-aanvraag is een periode. Door het bovenliggende bereik bij te houden, kan een hiërarchie van spans worden gevisualiseerd. Door spans van elke resource (proces) te verzamelen, kunt u het werk bijhouden dat plaatsvindt in een reeks services. HTTP-aanvragen hebben een header die wordt gebruikt om de traceId en parent spanId door te geven aan de volgende service. Elke resource moet telemetrie verzamelen en naar dezelfde collector verzenden. Vervolgens wordt een hiërarchie van de spanten samengevoegd en weergegeven.

Het dashboard bevat een lijst met traceringen met overzichtsgegevens. Telkens wanneer er spans met een nieuwe traceId worden gedetecteerd, krijgen deze een rij in de tabel. Als u op de weergave klikt, worden alle spanten in de trace weergegeven.

Als u een bereik selecteert, worden de details weergegeven, inclusief de eigenschappen van de span, zoals de greeting tag die u in stap 3 hebt ingesteld.