Partager via

Génération de la source de métrique au moment de la compilation

. L’infrastructure de contrôle de NET est conçue pour fournir une solution de mesure hautement utilisable et haute performance pour les applications .NET modernes.

Pour utiliser le contrôle généré par la source, créez une classe qui définit les noms et les dimensions des métriques que votre code peut produire. Ensuite, créez la classe en utilisant les signatures de méthode partial.

Le générateur source génère automatiquement le code, qui expose des types et méthodes de contrôle fortement typés que vous pouvez appeler pour enregistrer les valeurs de métrique. Les méthodes générées sont implémentées sous une forme très efficace, ce qui réduit la surcharge de calcul par rapport aux solutions de mesure traditionnelles.

Commencez

Pour commencer, installez le 📦 package NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Pour plus d’informations, consultez dotnet add package or Manage package dependencies in .NET applications.

Attributs génériques

Les attributs génériques nécessitent C# 11 ou version ultérieure. Pour C# 10 ou version antérieure, utilisez plutôt des attributs non générés.

L’exemple suivant montre une classe qui déclare trois métriques. Les méthodes sont marquées avec un attribut et sont déclarées comme static et partial. Le générateur de code s’exécute au moment de la génération et fournit une implémentation de ces méthodes, ainsi que des types associés.

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

Le code suivant montre comment utiliser le générateur avec des types primitifs :

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

Spécification d’unités

À compter de .NET 10.2, vous pouvez éventuellement spécifier une unité de mesure pour vos métriques à l’aide du Unit paramètre. Cela permet de fournir un contexte sur les mesures de métrique (par exemple, « secondes », « octets » et « demandes »). L’unité est transmise au sous-jacent Meter lors de la création de l’instrument.

Le code suivant montre comment utiliser le générateur avec des types primitifs avec des unités spécifiées :

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

La déclaration précédente retourne automatiquement les éléments suivants :

  • Latency classe avec une Record méthode
  • TotalCount classe avec une Add méthode
  • TotalFailures classe avec une Add méthode.

Les attributs indiquent l’ensemble des dimensions que chaque métrique utilise. La signature des types générés ressemble à ceci :

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

Les dimensions spécifiées dans les attributs ont été transformées en arguments pour les méthodes Add et Record. Vous utilisez ensuite les méthodes générées pour créer des instances de ces types. Avec les instances créées, vous pouvez appeler Add et Record inscrire des valeurs de métrique, comme illustré dans l’exemple suivant :

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

Exigences relatives aux méthodes de métrique

Les méthodes de métrique sont limitées aux éléments suivants :

  • Doivent être public static partial.
  • Le type de retour doit être unique.
  • Leurs noms ne doivent pas commencer par un trait de soulignement.
  • Leurs noms de paramètres ne doivent pas commencer par un trait de soulignement.
  • Leur premier paramètre doit être Meter de type.

Voir aussi

Pour plus d’informations sur les métriques prises en charge, consultez Types d’instruments pour savoir comment choisir l’instrument à utiliser dans différentes situations.

  • Last updated on