共用方式為

編譯時期指標來源生成

.NET 的計量基礎結構旨在為新式 .NET 應用程式提供高度可用且高效能的計量解決方案。

若要使用來源產生的計量，請建立類別，以定義程式代碼可產生之計量的名稱和維度。 然後，使用 partial 方法簽章建立 類別。

來源產生器會自動生成原始碼，這些原始碼會公開強類型的計量類型和方法，您可以呼叫這些方法來記錄計量值。 產生的方法會以高效形式實作，相較於傳統計量解決方案，可減少計算額外負荷。

開始

若要開始使用，請安裝 📦 Microsoft.Extensions.Telemetry.Abstractions NuGet 套件：

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

如需詳細資訊，請參閱 dotnet 新增套件 或在 .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