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

Dit is een van een reeks voorbeelden om .NET-waarneembaarheid met OpenTelemetry te illustreren.

Naast het feit dat het een standaardonderdeel van .NET Aspire is, is het Aspire Dashboard beschikbaar als een zelfstandige Docker-container, die een OTLP-eindpunttelemetrie biedt, kan worden verzonden en worden de logboeken, metrische gegevens en traceringen gevisualiseerd. Het gebruik van het dashboard op deze manier heeft geen afhankelijkheid van .NET Aspire, het visualiseert telemetrie van elke toepassing die telemetrie verzendt via OTLP. Het werkt even goed voor toepassingen die zijn geschreven in Java, GoLang, Python enzovoort. 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 die 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 het volgende 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 gotcha is het combineren van AppSettings.json en AppSettings.Development.json, als deze laatste aanwezig is, wordt deze gebruikt wanneer u F5 van Visual Studio gebruikt en alle instellingen in AppSettings.json worden genegeerd.

7. Start de Aspire Dashboard-container

Gebruik docker 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 zich 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 localhostdoor, bijvoorbeeld http://localhost:18888/login?t=123456780abcdef123456780 , open deze in uw browser, of u kunt de sleutel ook plakken nadat /login?t= het aanmeldingsdialoogvenster wordt weergegeven. 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 de telling verhoogd voor het aantal begroetingen dat is gedaan.

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 een aantal opties voor het uitgaan van logboeken vanuit .NET:

• stdout en stderr uitvoer wordt omgeleid naar logboekbestanden door containersystemen zoals Kubernetes.
• Met behulp van logboekbibliotheken die worden geïntegreerd met ILogger, zijn deze onder andere Serilog of 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, inventariseert 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 punten in de grafiek. Als u er een selecteert, gaat u naar de betreffende 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 te kijken naar specifieke dimensies, zoals alleen GET aanvragen of die voor een specifieke URL-route in ASP.NET.

8.3 De tracering weergeven

In de traceringsweergave wordt een lijst met traceringen weergegeven. Elke tracering is een set activiteiten die dezelfde traceId delen. Werk wordt bijgehouden met spanen die een werkeenheid vertegenwoordigen. Als u een ASP.NET aanvraag verwerkt, wordt een periode gemaakt. 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 het verzamelen van spanten van elke resource (proces) volgen we het werk dat plaatsvindt in een reeks services. Http-aanvragen hebben een header die wordt gebruikt om de traceId en bovenliggende 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.

In het dashboard wordt een lijst met traceringen met samenvattingsgegevens weergegeven. Wanneer er een nieuwe traceId wordt weergegeven, krijgen ze een rij in de tabel. Als u op de weergave klikt, worden alle spanten in de trace weergegeven.

Als u een span selecteert, worden de details weergegeven, inclusief eventuele eigenschappen in de periode, zoals de greeting tag die we in stap 3 hebben ingesteld.