Sdílet prostřednictvím

Generování zdroje metriky v čase kompilace

Infrastruktura měření .NET je navržená tak, aby poskytovala velmi dobře použitelné a velmi výkonné řešení měření pro moderní aplikace .NET.

Pokud chcete použít měření generované zdrojem, vytvořte třídu, která definuje názvy a dimenze metrik, které může váš kód vytvořit. Pak vytvořte třídu se signaturami metod partial.

Generátor kódů automaticky vygeneruje kód, který zpřístupňuje silně typované měřicí typy a metody, jež můžete použít k zaznamenání hodnot metrik. Generované metody jsou implementovány ve vysoce efektivní podobě, což snižuje výpočetní režii ve srovnání s tradičními řešeními měření.

Začínáme

Začněte instalací 📦 balíčku NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Další informace viz dotnet add package nebo Manage package dependencies in .NET applications.

Obecné atributy

Obecné atributy vyžadují C# 11 nebo novější. Pro C# 10 nebo starší použijte negenerické atributy.

Následující příklad ukazuje třídu, která deklaruje tři metriky. Metody jsou označeny atributem a jsou deklarovány jako static a partial. Generátor kódu běží v době sestavení a poskytuje implementaci těchto metod spolu s doprovodnými typy.

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

Následující kód ukazuje použití generátoru s primitivními typy:

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

Předchozí deklarace automaticky vrátí následující:

  • Latencytřída s metodou Record
  • TotalCounttřída s metodou Add
  • TotalFailures třída s metodou Add .

Atributy označují sadu dimenzí, které každá metrika používá. Podpis vygenerovaných typů vypadá takto:

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

Dimenze zadané v atributech byly převedeny na argumenty Add a Record metody. Potom použijete vygenerované metody k vytvoření instancí těchto typů. S vytvořenými instancemi můžete volat Add a Record a registrovat hodnoty metrik, jak je znázorněno v následujícím příkladu.

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

Požadavky na metody pro metriky

Metody metrik jsou omezené na následující:

  • Musí to být public static partial.
  • Návratový typ musí být jedinečný.
  • Jejich názvy nesmí začínat podtržítkem.
  • Názvy parametrů nesmí začínat podtržítkem.
  • První parametr musí být Meter typu.

Viz také

Další informace o podporovaných metrikách najdete v tématu Typy nástrojů , ve kterých se dozvíte, jak zvolit nástroj, který se má použít v různých situacích.

  • Last updated on