Fordítási idő alatti metrikai forrás generálása

. A NET mérési infrastruktúráját úgy tervezték, hogy magas rendelkezésre állású és nagy teljesítményű mérési megoldást biztosítson a modern .NET-alkalmazásokhoz.

A forrás által generált mérés használatához hozzon létre egy osztályt, amely meghatározza a kód által létrehozható metrikák nevét és dimenzióit. Ezután hozza létre az osztályt a metódus-aláírásokkal partial.

A forrásgenerátor automatikusan létrehozza a kódot, amely a metrikaértékek rögzítéséhez meghívható, erősen beírt mérési típusokat és metódusokat teszi elérhetővé. A generált módszerek rendkívül hatékony formában vannak implementálva, ami csökkenti a számítási többletterhelést a hagyományos mérési megoldásokhoz képest.

Első lépések

Első lépésként telepítse a 📦 Microsoft.Extensions.Telemetry.Abstractions NuGet csomagot:

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

További információ: dotnet add package vagy Csomagfüggőségek kezelése .NET alkalmazásokban.

Általános attribútumok

Az általános attribútumokhoz C# 11 vagy újabb verzió szükséges. C# 10 vagy korábbi esetén használjon nemgenerikus attribútumokat.

Az alábbi példa egy olyan osztályt mutat be, amely három metrikát deklarál. A metódusok attribútummal vannak megjelölve, és deklarálva vannak.staticpartial A kódgenerátor a létrehozáskor fut, és biztosítja ezeknek a módszereknek a implementációját a kísérő típusokkal együtt.

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

Az alábbi kód bemutatja, hogyan használhatja a generátort primitív típusokkal:

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

Egységek megadása

A .NET 10.2-től kezdve opcionálisan megadhatja a metrikák mértékegységét a Unit paraméterrel. Ez segít kontextust biztosítani a metrika mértékeiről (például "másodperc", "bájt" és "kérések"). Az egység az alapul szolgáló Meter részére kerül továbbításra a készülék létrehozásakor.

Az alábbi kód bemutatja, hogyan használhatja a generátort primitív típusokkal a megadott egységekkel:

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

Az előző deklaráció automatikusan a következőket adja vissza:

  • Latency osztály egy Record metódussal
  • TotalCount osztály egy Add metódussal
  • TotalFailures osztályt egy Add metódussal.

Az attribútumok az egyes metrikák által használt dimenziókészletet jelölik. A létrehozott típusok aláírása a következőképpen néz ki:

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

Az attribútumokban megadott dimenziók argumentumokká lettek alakítva a Add és Record metódusok számára. Ezután a létrehozott metódusokkal hozhat létre ilyen típusú példányokat. Miután a példányok létrejöttek, meghívhatja Add és Record a metrikaértékek regisztrálására, ahogy az alábbi példában látható.

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

Metrikametikai módszerek követelményei

A metrikametikai módszerek a következőkre vannak korlátozva:

  • Ennek public static partial kell lennie.
  • A visszatérési típusnak egyedinek kell lennie.
  • A nevük nem kezdődhet aláhúzásjellel.
  • A paraméternevek nem kezdődnek aláhúzásjellel.
  • Az első paraméternek típusnak kell lennie Meter .

Lásd még

A támogatott metrikákkal kapcsolatos további információkért tekintse meg az eszközök típusait , amelyekből megtudhatja, hogyan választhatja ki a különböző helyzetekben használni kívánt eszközt.

  • Last updated on