Condividi tramite

Generazione dell'origine delle metriche in fase di compilazione

. L'infrastruttura di misurazione di NET è progettata per offrire una soluzione di misurazione altamente utilizzabile e ad alte prestazioni per le applicazioni .NET moderne.

Per usare la misurazione generata dall'origine, creare una classe che definisce i nomi e le dimensioni delle metriche che il codice può produrre. Creare quindi la classe con le firme dei metodi partial.

Il generatore di origine genera automaticamente il codice, che espone tipi e metodi di misurazione fortemente tipizzati che è possibile richiamare per registrare i valori delle metriche. I metodi generati vengono implementati in un formato estremamente efficiente, riducendo il sovraccarico di calcolo rispetto alle soluzioni tradizionali di misurazione.

Inizia subito

Per iniziare, installare il 📦 pacchetto NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Per altre informazioni, vedere dotnet add package o Gestire le dipendenze dei pacchetti nelle applicazioni .NET.

Attributi generici

Gli attributi generici richiedono C# 11 o versione successiva. Per C# 10 o versioni precedenti, usare invece attributi non generici.

L'esempio seguente mostra una classe che dichiara tre metriche. I metodi sono contrassegnati con un attributo e vengono dichiarati come static e partial. Il generatore di codice viene eseguito in fase di compilazione e fornisce un'implementazione di questi metodi, insieme ai tipi associati.

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

Il codice seguente illustra come usare il generatore con tipi primitivi:

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

Specifica delle unità

A partire da .NET 10.2, è possibile specificare facoltativamente un'unità di misura per le metriche usando il Unit parametro . Ciò consente di fornire contesto sulle misure delle metriche, ad esempio "secondi", "byte" e "richieste". L'unità viene passata al componente sottostante Meter durante la creazione dello strumento.

Il codice seguente illustra come usare il generatore con tipi primitivi con unità specificate:

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 dichiarazione precedente restituisce automaticamente quanto segue:

  • Latency classe con un Record metodo
  • TotalCount classe con un Add metodo
  • TotalFailures classe con un Add metodo.

Gli attributi indicano il set di dimensioni usate da ogni metrica. La firma per i tipi generati è simile alla seguente:

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

Le dimensioni specificate negli attributi sono state trasformate in argomenti per i metodi Add e Record. Usare quindi i metodi generati per creare istanze di questi tipi. Con le istanze create, è possibile chiamare Add e Record registrare i valori delle metriche, come illustrato nell'esempio seguente:

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

Requisiti dei metodi di metrica

I metodi delle metriche sono vincolati ai seguenti:

  • Devono essere public static partial.
  • Il tipo restituito deve essere univoco.
  • I nomi non devono iniziare con un carattere di sottolineatura.
  • I nomi dei parametri non devono iniziare con un carattere di sottolineatura.
  • Il loro primo parametro deve avere il tipo Meter.

Vedere anche

Per altre informazioni sulle metriche supportate, vedere Tipi di strumenti per informazioni su come scegliere quale strumento usare in situazioni diverse.

  • Last updated on