Példa: OpenTelemetria használata az OTLP-vel és az önálló Aspire-irányítópulttal

Ez egy példasorozat a .NET OpenTelemetryvel való megfigyelhetőségének szemléltetésére.

A .NET Aspire standard része mellett az Aspire-irányítópult önálló docker-tárolóként is elérhető, amely egy OTLP-végpont telemetriát biztosít, és megjeleníti a naplókat, metrikákat és nyomkövetéseket. Az irányítópult ily módon történő használata nem függ a .NET Aspire-től, a telemetria bármely alkalmazásból, amely telemetriát küld az OTLP-n keresztül. Ugyanúgy működik a Java, GoLang, Python stb. nyelven írt alkalmazásokhoz is. feltéve, hogy elküldhetik a telemetriájukat egy OTLP-végpontra.

Az Aspire-irányítópult használata kevesebb konfigurációs és beállítási lépéssel rendelkezik, mint a nyílt forráskódú megoldások, például a Prometheus, a Grafana és a Jaeger használata, de az ilyen eszközökkel ellentétben az Aspire irányítópult fejlesztői vizualizációs eszközként, nem pedig éles monitorozásra szolgál.

1. A projekt létrehozása

Hozzon létre egy egyszerű webes API-projektet a ASP.NET Core Empty sablonnal a Visual Studióban vagy a következő .NET CLI-paranccsal:

dotnet new web

2. Metrikák és tevékenységdefiníciók hozzáadása

Az alábbi kód egy új metrikát (greetings.count) határoz meg az API meghívásának hányszori számához, valamint egy új tevékenységforráshoz (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. API-végpont létrehozása

Szúrja be a következőt:builder.Build();app.Run()

app.MapGet("/", SendGreeting);

Szúrja be a következő függvényt a fájl alján:

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

4. Hivatkozás az OpenTelemetry-csomagokra

A NuGet-Csomagkezelő vagy parancssor használatával vegye fel a következő NuGet-csomagokat:

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

5. OpenTelemetria konfigurálása a megfelelő szolgáltatókkal

Szúrja be a következő kódot a következő elé 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();
}

Ez a kód beállítja az OpenTelemetryt a különböző telemetriai forrásokkal:

• OTel-szolgáltatót ad hozzá az ILoggerhez a naplórekordok gyűjtéséhez.
• Beállítja a metrikákat, regisztrálja a rendszerállapot-szolgáltatókat és a mérőszámokat a ASP.NET és az egyéni mérőszámunkhoz.
• Beállítja a nyomkövetést, regisztrálja a rendszerállapot-szolgáltatókat és az egyéni ActivitySource-t.

Ezután env vars használatával regisztrálja az OTLP-exportőrt a konfigurációjához.

6. AZ OTLP környezeti változóinak konfigurálása

Az OTLP-exportőr api-kkal konfigurálható kódban, de gyakoribb, hogy környezeti változókon keresztül konfigurálja. Adja hozzá a következőket a AppSettings.Development.json

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

További környezeti változókat adhat hozzá a .NET OTLP-exportőrhöz vagy a gyakori OTel-változókhoz, például OTEL_RESOURCE_ATTRIBUTES erőforrásattribútumok definiálásához.

7. Indítsa el az Aspire Irányítópult-tárolót

Töltse le és futtassa az irányítópult-tárolót a Docker használatával.

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

Az irányítópulton megjelenített adatok bizalmasak lehetnek. Alapértelmezés szerint az irányítópult hitelesítéssel van védve, amelyhez jogkivonat szükséges a bejelentkezéshez. A jogkivonat a tároló futtatásakor jelenik meg az eredményben.

[]

Másolja ki a megjelenő URL-címet, és cserélje le 0.0.0.0 localhostpéldául http://localhost:18888/login?t=123456780abcdef123456780 és nyissa meg a böngészőben, vagy beillesztheti a kulcsot a bejelentkezési párbeszédpanel megjelenítése után /login?t= is. A jogkivonat minden alkalommal megváltozik, amikor elindítja a tárolót.

8. A projekt futtatása

Futtassa a projektet, majd nyissa meg az API-t a böngészőben vagy a curlben.

curl -k http://localhost:7275

Minden alkalommal, amikor a lapot kéri, az növeli a megszólítások számát.

8.1 Naplókimenet

A kódból származó naplózási utasítások kimenete a következő ILogger: . Alapértelmezés szerint a konzolszolgáltató engedélyezve van, így a kimenet a konzolra lesz irányítva.

A naplók .NET-ből való kimenő forgalmának több lehetősége is van:

• stdout és stderr a kimenetet a tárolórendszerek, például a Kubernetes átirányítják a naplófájlokhoz.
• Az ILoggerrel integrálható naplózási kódtárak használatával ezek közé tartozik a Serilog vagy az NLog.
• Naplózási szolgáltatók használata az OTelhez, például az OTLP-hez. Az 5. lépésben található kód naplózási szakasza hozzáadja az OTel-szolgáltatót.

A naplók strukturált naplókként jelennek meg az irányítópulton – a naplóüzenetben megadott tulajdonságok a naplórekord mezőiként lesznek kinyerve.

8.2 A metrikák megtekintése

Az Aspire-irányítópult erőforrásonként jeleníti meg a metrikákat (ez az erőforrás az OTel módja a telemetriai forrásokról, például egy folyamatról való beszélgetéshez). Ha kijelöl egy erőforrást, az irányítópult számba veszi azokat a metrikákat, amelyeket az erőforrás küldött az OTLP-végpontjára. A metrikák listája dinamikus, és az új metrikák érkeznek.

A metrikák nézete a használt metrikák típusától függ:

• A számlálók közvetlenül jelennek meg.
• A kérelemenkénti értékeket nyomon követő hisztogramokat, például az időbélyeget vagy a kérésenként küldött bájtokat a rendszer gyűjtők sorozatába gyűjti. Az irányítópult a P50, a P90 és a P99 percentiliseket ábrázolja. A hisztogram eredményei lehetnek példaképek, amelyek egyedi adatpontok, valamint a kérelem nyomkövetési/spanId azonosítója. Ezek pontként jelennek meg a gráfon. Ha kiválaszt egyet, a megfelelő nyomkövetésre lép, hogy láthassa, mi okozta ezt az értéket. Ez hasznos a kiugró értékek diagnosztizálásához.
• A metrikák tartalmazhatnak dimenziókat, amelyek az egyes értékekhez társított kulcs-érték párok. Az értékek dimenziónként vannak összesítve. A nézetben található legördülő listák segítségével szűrheti az eredményeket, hogy megtekintse az adott dimenziókat, például csak GET a kérelmeket, vagy azokat, amelyek egy adott URL-útvonalra vonatkoznak ASP.NET.

8.3 A nyomkövetés megtekintése

A nyomkövetési nézet a nyomkövetések listáját jeleníti meg – minden nyomkövetés olyan tevékenységcsoport, amely ugyanazt a traceId azonosítót használja. A munka a munkaegységet jelentő spanokkal van nyomon követve. A ASP.NET kérés feldolgozása egy időtartamot hoz létre. A HttpClient-kérések létrehozása egy időtartam lesz. A span szülőjének nyomon követésével a spanok hierarchiája vizualizálható. Az egyes erőforrásokból (folyamatokból) származó spanok gyűjtésével nyomon követjük azokat a munkát, amelyek számos szolgáltatásban történnek. A HTTP-kérések fejléce a traceId és a szülő spanId átadására szolgál a következő szolgáltatásnak. Minden erőforrásnak telemetriát kell gyűjtenie, és ugyanarra a gyűjtőre kell küldenie. Ezután összesíti és megjeleníti a spanok hierarchiáját.

Az irányítópult megjeleníti a nyomkövetések listáját összefoglaló információkkal. Amikor egy új traceId-azonosítóval való átfedés jelenik meg, egy sor jelenik meg a táblában. A kattintási nézetben megjelenik a nyomkövetés összes spanja.

A span kiválasztásakor megjelennek a részletek, beleértve a 3. lépésben beállított címkét is.greeting