Kompileringstid metrisk källgenerering

. NET:s avläsningsinfrastruktur är utformad för att leverera en mycket användbar och högpresterande mätningslösning för moderna .NET-program.

Om du vill använda källgenererad mätning skapar du en klass som definierar namn och dimensioner för de mått som koden kan producera. Skapa sedan klassen med partial metodsignaturer.

Källgeneratorn genererar automatiskt koden, som exponerar starkt typbeskrivna mätningstyper och metoder som du kan anropa för att registrera måttvärden. De genererade metoderna implementeras i en mycket effektiv form, vilket minskar beräkningskostnaderna jämfört med traditionella mätningslösningar.

Kom igång

Kom igång genom att 📦 installera NuGet-paketet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry.Abstractions"
                    Version="*" />
</ItemGroup>

Mer information finns i dotnet add package eller på Hantera paketsberoenden i .NET-applikationer.

Allmänna attribut

Allmänna attribut kräver C# 11 eller senare. För C# 10 eller tidigare använder du icke-generiska attribut i stället.

I följande exempel visas en klass som deklarerar tre mått. Metoderna markeras med ett attribut och deklareras som static och partial. Kodgeneratorn körs vid byggtiden och tillhandahåller en implementering av dessa metoder, tillsammans med tillhörande typer.

internal class MetricConstants
{
    public const string EnvironmentName = "env";
    public const string Region = "region";
    public const string RequestName = "requestName";
    public const string RequestStatus = "requestStatus";
}

Följande kod visar hur du använder generatorn med primitiva typer:

using System.Diagnostics.Metrics;
using Microsoft.Extensions.Diagnostics.Metrics;

namespace MetricsGen;

internal static partial class Metric
{
    // an explicit metric name is given
    [Histogram<long>("requestName", "duration", Name = "MyCustomMetricName")]
    public static partial Latency CreateLatency(Meter meter);

    // no explicit metric name given, it is auto-generated from the method name
    [Counter<int>(
        MetricConstants.EnvironmentName,
        MetricConstants.Region,
        MetricConstants.RequestName,
        MetricConstants.RequestStatus)]
    public static partial TotalCount CreateTotalCount(Meter meter);

    [Counter<int>]
    public static partial TotalFailures CreateTotalFailures(this Meter meter);
}

Föregående deklaration returnerar automatiskt följande:

• Latency klass med en Record metod
• TotalCount klass med en Add metod
• TotalFailures -klass med en Add metod.

Attributen anger den uppsättning dimensioner som varje mått använder. Signaturen för de genererade typerna ser ut så här:

internal class TotalCount
{
    public void Add(int value, object? env, object? region, object? requestName, object? requestStatus)
}

internal class TotalFailures
{
    public void Add(int value)
}

internal class Latency
{
    public void Record(long value, object? requestName, object? duration);
}

De dimensioner som anges i attributen har omvandlats till argument till Add metoderna och Record . Sedan använder du de genererade metoderna för att skapa instanser av dessa typer. När instanserna har skapats kan du anropa Add och Record registrera måttvärden, som du ser i följande exempel:

internal class MyClass
{
    // these variable are for example purposes, the dimensions values should depend on your business logic.
    private string envName = "envValue";
    private string regionName = "regionValue";
    private string requestName = "requestNameValue";
    private string status = "requestStatusValue";
    private string duration = "1:00:00";

    private readonly Latency _latencyMetric;
    private readonly TotalCount _totalCountMetric;
    private readonly TotalFailures _totalFailuresMetric;

    public MyClass(Meter meter)
    {
        // Create metric instances using the source-generated factory methods
        _latencyMetric = Metric.CreateLatency(meter);
        _totalCountMetric = Metric.CreateTotalCount(meter);
        // This syntax is available since `CreateTotalFailures` is defined as an extension method
        _totalFailuresMetric = meter.CreateTotalFailures();
    }

    public void ReportSampleRequestCount()
    {
        // method logic ...

        // Invoke Add on the counter and pass the dimension values you need.
        _totalCountMetric.Add(1, envName, regionName, requestName, status);
    }

    public void ReportSampleLatency()
    {
        // method logic ...

        // Invoke Record on the histogram and pass the dimension values you need.
        _latencyMetric.Record(1, requestName, duration);
    }

    public void ReportSampleFailuresCount()
    {
        // method logic ...

        // Invoke Add on the counter and pass the dimension values you need.
        _totalFailuresMetric.Add(1);
    }
}

Krav för måttmetoder

Måttmetoder är begränsade till följande:

• De måste vara public static partial.
• Returtypen måste vara unik.
• Deras namn får inte börja med ett understreck.
• Deras parameternamn får inte börja med ett understreck.
• Deras första parameter måste vara Meter typ.

Se även

Mer information om mått som stöds finns i Typer av instrument för att lära dig hur du väljer vilket instrument som ska användas i olika situationer.