Bagikan melalui

Pembuatan sumber metrik waktu kompilasi

. Infrastruktur pengukuran NET dirancang untuk memberikan solusi pengukuran yang sangat dapat digunakan dan berkinerja tinggi untuk aplikasi .NET modern.

Untuk menggunakan pengukuran yang dihasilkan sumber, buat kelas yang menentukan nama dan dimensi metrik yang dapat dihasilkan kode Anda. Kemudian, buat kelas dengan partial definisi metode.

Generator kode secara otomatis menghasilkan kode, yang mengekspos jenis dan metode pengukuran tipe kuat yang dapat Anda gunakan untuk merekam nilai metrik. Metode yang dihasilkan diimplementasikan dalam bentuk yang sangat efisien, yang mengurangi overhead komputasi dibandingkan dengan solusi pengukuran tradisional.

Mulai sekarang!

Untuk memulai, instal 📦 paket NuGet Microsoft.Extensions.Telemetry.Abstractions :

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

Untuk informasi selengkapnya, lihat dotnet menambahkan paket atau Mengelola dependensi paket dalam aplikasi .NET.

Atribut generik

Atribut generik memerlukan C# 11 atau yang lebih baru. Untuk C# 10 atau yang lebih lama, gunakan atribut nongenerik sebagai gantinya.

Contoh berikut menunjukkan kelas yang mendeklarasikan tiga metrik. Metode ditandai dengan atribut dan dinyatakan sebagai static dan partial. Generator kode berjalan pada waktu build dan menyediakan implementasi metode ini, bersama dengan jenis yang menyertainya.

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

Kode berikut menunjukkan cara menggunakan generator dengan jenis primitif:

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

Menentukan unit

Dimulai dengan .NET 10.2, Anda dapat secara opsional menentukan satuan pengukuran untuk metrik Anda menggunakan Unit parameter . Ini membantu memberikan konteks tentang apa yang diukur metrik (misalnya, "detik", "byte", dan "permintaan"). Unit diteruskan ke lapisan bawah Meter saat membuat instrumen.

Kode berikut menunjukkan cara menggunakan generator dengan jenis primitif dengan unit yang ditentukan:

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

Deklarasi sebelumnya secara otomatis mengembalikan yang berikut ini:

  • Kelas Latency dengan metode Record
  • TotalCount kelas dengan metode Add
  • TotalFailures kelas dengan Add metode.

Atribut menunjukkan kumpulan dimensi yang digunakan setiap metrik. Tanda tangan untuk jenis yang dihasilkan terlihat seperti ini:

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

Dimensi yang ditentukan dalam atribut telah diubah menjadi argumen untuk metode Add dan Record. Anda kemudian menggunakan metode yang dihasilkan untuk membuat instans jenis ini. Dengan instans yang dibuat, Anda dapat memanggil Add dan Record mendaftarkan nilai metrik, seperti yang ditunjukkan dalam contoh berikut:

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

Persyaratan metode metrik

Metode metrik dibatasi untuk hal berikut:

  • Mereka harus public static partial.
  • Jenis pengembalian harus unik.
  • Nama mereka tidak boleh dimulai dengan garis bawah.
  • Nama parameter mereka tidak boleh dimulai dengan garis bawah.
  • Parameter pertama mereka harus Meter jenis.

Lihat juga

Untuk informasi selengkapnya tentang metrik yang didukung, lihat Jenis instrumen untuk mempelajari cara memilih instrumen mana yang akan digunakan dalam situasi yang berbeda.

  • Last updated on