次の方法で共有

コンパイル時のメトリック ソースの生成

.NET の測定インフラストラクチャは、最新の .NET アプリケーション向けに、非常に使いやすく、高パフォーマンスの測定ソリューションを提供するように設計されています。

ソース生成の測定を使用するには、コードで生成できるメトリックの名前とディメンションを定義するクラスを作成します。 次に、 partial メソッド シグネチャを使用してクラスを作成します。

ソース ジェネレーターによってコードが自動的に生成されます。これにより、メトリック値を記録するために呼び出すことができる厳密に型指定された測定の種類とメソッドが公開されます。 生成されたメソッドは、従来の測定ソリューションと比較して計算オーバーヘッドを削減する、非常に効率的な形式で実装されます。

始めましょう

開始するには、 📦 Microsoft.Extensions.Telemetry.Abstractions NuGet パッケージをインストールします。

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

詳しくは、「dotnet add package」または「.NET アプリケーションでパッケージの依存関係を管理する」をご覧ください。

汎用属性

ジェネリック属性には C# 11 以降が必要です。 C# 10 以前の場合は、代わりに非ジェネリック属性を使用します。

次の例は、3 つのメトリックを宣言するクラスを示しています。 メソッドは属性でマークされ、 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);
}

前の宣言では、次のものが自動的に返されます。

  • Latency Record メソッドを持つクラス
  • TotalCount Add メソッドを持つクラス
  • TotalFailures Add メソッドを持つクラス。

属性は、各メトリックが使用するディメンションのセットを示します。 生成された型のシグネチャは次のようになります。

internal class TotalCount
{
    public void Add(int value, object? env, object? region, object? requestName, object? requestStatus)
}

internal 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 型である必要があります。 メトリック メソッドは、次のように制限されます。

こちらも参照ください

サポートされているメトリックの詳細については、さまざまな状況で使用する機器を選択する方法を学習する インストルメントの種類 を参照してください。