Udostępnij przez

Tworzenie źródeł metryk w czasie kompilacji

Infrastruktura metryki platformy .NET została zaprojektowana, aby dostarczać wyjątkowo użyteczne i wydajne rozwiązanie dla nowoczesnych aplikacji .NET.

Aby użyć pomiarów generowanych przez źródło, utwórz klasę, która definiuje nazwy i wymiary metryk, które może wygenerować kod. Następnie utwórz klasę z podpisami partial metod.

Generator źródła automatycznie generuje kod, który uwidacznia silnie typizowane typy pomiarów i metody, które można wywołać w celu rejestrowania wartości metryk. Wygenerowane metody są implementowane w wysoce wydajnej formie, co zmniejsza obciążenie obliczeniowe w porównaniu z tradycyjnymi rozwiązaniami pomiarów.

Wprowadzenie

Aby rozpocząć, zainstaluj 📦 pakiet NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Aby uzyskać więcej informacji, zobacz dotnet add package lub Zarządzanie zależnościami pakietów w aplikacjach platformy .NET.

Atrybuty ogólne

Atrybuty ogólne wymagają języka C# 11 lub nowszego. W przypadku języka C# 10 lub starszego użyj atrybutów niegenerycznych.

W poniższym przykładzie przedstawiono klasę, która deklaruje trzy metryki. Metody są oznaczone atrybutem i są deklarowane jako static i partial. Generator kodu jest uruchamiany w czasie kompilacji i zapewnia implementację tych metod wraz z towarzyszącymi typami.

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

Poniższy kod pokazuje, jak używać generatora z typami pierwotnymi:

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

Określanie jednostek

Począwszy od platformy .NET 10.2, możesz opcjonalnie określić jednostkę miary dla metryk przy użyciu parametru Unit . Pomaga to określić kontekst miar metryki (na przykład "sekundy", "bajty" i "żądania"). Jednostka jest przekazywana do bazowego Meter podczas tworzenia instrumentu.

Poniższy kod pokazuje, jak używać generatora z typami pierwotnymi z określonymi jednostkami:

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

Poprzednia deklaracja automatycznie zwraca następujące elementy:

  • Latency klasa z Record metodą
  • TotalCount klasa z Add metodą
  • TotalFailures klasa z Add metodą.

Atrybuty wskazują zestaw wymiarów, których używa każda metryka. Podpis wygenerowanych typów wygląda następująco:

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

Wymiary określone w atrybutach zostały przekształcone w argumenty metod Add i Record. Następnie użyj wygenerowanych metod, aby utworzyć wystąpienia tych typów. Po utworzeniu wystąpień można wywołać Add i Record do zarejestrowania wartości metryk, jak w poniższym przykładzie:

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

Wymagania dotyczące metod metryk

Metody metryczne są ograniczone do następujących elementów:

  • Muszą mieć wartość public static partial.
  • Zwracany typ musi być unikatowy.
  • Ich nazwy nie mogą zaczynać się od podkreślnika.
  • Ich nazwy parametrów nie mogą rozpoczynać się od podkreślnika.
  • Ich pierwszy parametr musi być Meter typem.

Zobacz także

Aby uzyskać więcej informacji na temat obsługiwanych metryk, zobacz Typy instrumentów , aby dowiedzieć się, jak wybrać instrument do użycia w różnych sytuacjach.

  • Last updated on