Freigeben über

Quellenerzeugung für Kompilierungszeitmetriken

. Die Meteringinfrastruktur von NET wurde entwickelt, um eine hochverwendbare und leistungsstarke Meteringlösung für moderne .NET-Anwendungen bereitzustellen.

Erstellen Sie eine Klasse, die die Namen und Dimensionen der Metriken definiert, die Ihr Code erzeugen kann, um die vom Quell generierten Metering zu verwenden. Erstellen Sie dann die Klasse mit partial Methodensignaturen.

Der Quellgenerator generiert automatisch den Code, der stark typierte Meteringtypen und -methoden verfügbar macht, die Sie aufrufen können, um Metrikwerte aufzuzeichnen. Die generierten Methoden werden in einer hocheffizienten Form implementiert, wodurch der Berechnungsaufwand im Vergleich zu herkömmlichen Messlösungen reduziert wird.

Loslegen

Installieren Sie zunächst das 📦 NuGet-Paket "Microsoft.Extensions.Telemetry.Abstractions NuGet":

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Weitere Informationen finden Sie unter dotnet add package or Manage package dependencies in .NET applications.

Generische Attribute

Generische Attribute erfordern C# 11 oder höher. Verwenden Sie für C# 10 oder früheren Versionen stattdessen nichtgenerische Attribute.

Das folgende Beispiel zeigt eine Klasse, die drei Metriken deklariert. Die Methoden werden mit einem Attribut gekennzeichnet und als static und partialdeklariert. Der Codegenerator wird während der Build-Zeit ausgeführt und stellt eine Implementierung dieser Methoden zusammen mit zugehörigen Typen bereit.

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

Der folgende Code veranschaulicht die Verwendung des Generators mit primitiven Typen:

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);
}

Angeben von Einheiten

Ab .NET 10.2 können Sie optional eine Maßeinheit für Ihre Metriken mithilfe des Unit Parameters angeben. Dies hilft dabei, Kontext darüber bereitzustellen, was die Metrik misst (z. B. "Sekunden", "Bytes" und "Anforderungen"). Die Einheit wird beim Erstellen des Instruments an den zugrunde liegenden Meter übergeben.

Der folgende Code veranschaulicht die Verwendung des Generators mit primitiven Typen mit angegebenen Einheiten:

internal static partial class Metric
{
    [Histogram<long>("requestName", "duration", Name = "MyCustomMetricName", Unit = "ms")]
    public static partial Latency CreateLatency(Meter meter);

    [Counter<int>(
        MetricConstants.EnvironmentName,
        MetricConstants.Region,
        MetricConstants.RequestName,
        MetricConstants.RequestStatus,
        Unit = "requests")]
    public static partial TotalCount CreateTotalCount(Meter meter);

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

Die vorherige Deklaration gibt automatisch Folgendes zurück:

  • Latency Klasse mit einer Record Methode
  • TotalCount Klasse mit einer Add Methode
  • TotalFailures klasse mit einer Add Methode.

Die Attribute geben den Satz von Dimensionen an, die von den einzelnen Metriken verwendet werden. Die Signatur für die generierten Typen sieht wie folgt aus:

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);
}

Die in den Attributen angegebenen Dimensionen wurden in Argumente für die Add Und Record Methoden umgewandelt. Anschließend verwenden Sie die generierten Methoden, um Instanzen dieser Typen zu erstellen. Mit den erstellten Instanzen können Sie Add und Record verwenden, um Metrikwerte zu registrieren, wie im folgenden Beispiel gezeigt:

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);
    }
}

Anforderungen an Metrikmethoden

Metrikmethoden sind auf Folgendes beschränkt:

  • Sie müssen public static partial sein.
  • Der Rückgabetyp muss eindeutig sein.
  • Ihre Namen dürfen nicht mit einem Unterstrich beginnen.
  • Die Parameternamen dürfen nicht mit einem Unterstrich beginnen.
  • Der erste Parameter muss vom Typ Meter sein.

Siehe auch

Weitere Informationen zu den unterstützten Metriken finden Sie unter "Arten von Instrumenten ", um zu erfahren, wie Sie auswählen, welches Instrument in verschiedenen Situationen verwendet werden soll.

  • Last updated on