Бөлісу құралы:

Создание источника метрик во время компиляции

Инфраструктура измерений .NET предназначена для обеспечения удобного в использовании и высокопроизводительного решения для современных приложений .NET.

Чтобы использовать метрики, созданные источником, создайте класс, определяющий имена и измерения метрик, которые может создавать код. Затем создайте класс с partial сигнатурами метода.

Генератор источника автоматически создает код, который предоставляет строго типизированные типы и методы измерения, которые можно вызвать для записи значений метрик. Созданные методы реализуются в высоко эффективной форме, что снижает затраты на вычисления по сравнению с традиционными решениями измерения.

Начало работы

Чтобы приступить к работе, установите 📦 пакет NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Дополнительные сведения см. в разделе dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Универсальные атрибуты

Универсальные атрибуты требуют C# 11 или более поздней версии. Для C# 10 или более ранних версий используйте вместо этого негенерические атрибуты.

В следующем примере показан класс, объявляющий три метрики. Методы помечены атрибутом и объявляются как static и partial. Генератор кода выполняется во время сборки и предоставляет реализацию этих методов вместе с сопутствующими типами.

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

В следующем коде показано, как использовать генератор с примитивными типами:

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

Указание единиц

Начиная с .NET 10.2, можно также указать единицу измерения для метрик с помощью Unit параметра. Это помогает предоставить контекст о том, что измеряет метрика (например, "секунды", "байты" и "запросы"). Единица передается базовому Meter элементу при создании инструмента.

В следующем коде показано, как использовать генератор с примитивными типами с указанными единицами:

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

Предыдущее объявление автоматически возвращает следующую информацию:

  • Latencyкласс с методом Record
  • TotalCountкласс с методом Add
  • TotalFailures класс с методом Add .

Атрибуты указывают набор измерений, которые используются каждой метрикой. Сигнатура для созданных типов выглядит следующим образом:

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

Измерения, указанные в атрибутах, были превращены в аргументы методов Add и Record. Затем вы используете созданные методы для создания экземпляров этих типов. С помощью созданных экземпляров можно вызывать Add и Record регистрировать значения метрик, как показано в следующем примере:

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

Требования к методам метрик

Метрические методы ограничены следующим:

  • Они должны быть public static partial.
  • Возвращаемый тип должен быть уникальным.
  • Их имена не должны начинаться с подчеркивания.
  • Имена параметров не должны начинаться с символа подчеркивания.
  • Их первый параметр должен быть Meter типом.

См. также

Дополнительные сведения о поддерживаемых метриках см. в разделе "Типы инструментов ", чтобы узнать, как выбрать инструмент для использования в разных ситуациях.

  • Last updated on