Aracılığıyla paylaş

Derleme zamanı metrik kaynak üretimi

. NET'in ölçüm altyapısı, modern .NET uygulamaları için yüksek oranda kullanılabilir ve yüksek performanslı bir ölçüm çözümü sunmak üzere tasarlanmıştır.

Kaynak tarafından oluşturulan ölçümü kullanmak için kodunuzun üretebileceği ölçümlerin adlarını ve boyutlarını tanımlayan bir sınıf oluşturun. Ardından, yöntem imzalarıyla partial sınıfını oluşturun.

Kaynak oluşturucu otomatik olarak kodu oluşturur ve bu kod, ölçüm değerlerini kaydetmek için çağırabileceğiniz kesin olarak belirlenmiş ölçüm türlerini ve yöntemlerini kullanıma sunar. Oluşturulan yöntemler, geleneksel ölçüm çözümlerine kıyasla hesaplama ek yükünü azaltan son derece verimli bir biçimde uygulanır.

Başlayın

Başlamak için Microsoft.Extensions.Telemetry.Abstractions NuGet paketini yükleyin📦:

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Daha fazla bilgi için bkz. dotnet add package veya Manage package dependencies in .NET applications.

Genel öznitelikler

Genel öznitelikler C# 11 veya üzerini gerektirir. C# 10 veya önceki sürümler için bunun yerine genel olmayan öznitelikleri kullanın.

Aşağıdaki örnekte üç ölçüm bildiren bir sınıf gösterilmektedir. Yöntemler bir öznitelikle işaretlenir ve static ve partial olarak bildirilir. Kod oluşturucu derleme zamanında çalışır ve eşlik eden türlerin yanı sıra bu yöntemlerin bir uygulamasını sağlar.

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

Aşağıdaki kod, oluşturucunun ilkel türlerle nasıl kullanılacağını gösterir:

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

Birimleri belirtme

.NET 10.2'den başlayarak, isteğe bağlı olarak parametresini kullanarak Unit ölçümleriniz için bir ölçü birimi belirtebilirsiniz. Bu, ölçümün ölçüleri hakkında bağlam sağlamaya yardımcı olur (örneğin, "saniye", "bayt" ve "istekler"). Ünite, cihaz oluşturulurken altta yatan Meter üzerine geçirilir.

Aşağıdaki kod, belirtilen birimlerle birlikte ilkel türlerle jeneratörün nasıl kullanılacağını gösterir.

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

Önceki bildirim otomatik olarak aşağıdakileri döndürür:

  • Latency yöntemiyle Record sınıf
  • TotalCount Add yöntemine sahip sınıf
  • TotalFailures yöntemine sahip bir Add sınıfı.

Öznitelikler, her ölçümün kullandığı boyut kümesini gösterir. Oluşturulan türlerin imzası şöyle görünür:

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

Özniteliklerde belirtilen boyutlar, Add ve Record yöntemleri için bağımsız değişkenlere dönüştürüldü. Ardından, bu türlerin örneklerini oluşturmak için oluşturulan yöntemleri kullanırsınız. Örnekler oluşturulduktan sonra, aşağıdaki örnekte gösterildiği gibi metrik değerlerini kaydetmek için Add ve Record öğelerini çağırabilirsiniz:

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

Ölçüm yöntemleri gereksinimleri

Ölçüm yöntemleri aşağıdakilerle kısıtlanır:

  • Onlar olmalı public static partial.
  • Dönüş türü benzersiz olmalıdır.
  • Adları alt çizgiyle başlamamalıdır.
  • Parametre adları alt çizgiyle başlamamalıdır.
  • İlk parametreleri tür olmalıdır Meter .

Ayrıca bakınız

Desteklenen ölçümler hakkında daha fazla bilgi için farklı durumlarda hangi aletin kullanılacağını seçmeyi öğrenmek için bkz. Araç türleri.

  • Last updated on