다음을 통해 공유

컴파일 시간 메트릭 원본 생성

. NET의 계량 인프라는 최신 .NET 애플리케이션에 매우 사용 가능하고 고성능 계량 솔루션을 제공하도록 설계되었습니다.

소스 생성 계량 기능을 사용하려면 코드에서 생성할 수 있는 메트릭의 이름과 차원을 정의하는 클래스를 만듭니다. 그런 다음 메서드 시그니처를 사용하여 partial 클래스를 만듭니다.

소스 생성기는 메트릭 값을 기록하기 위해 호출할 수 있는 강력한 형식의 계량 형식 및 메서드를 노출하는 코드를 자동으로 생성합니다. 생성된 메서드는 기존의 계량 솔루션에 비해 계산 오버헤드를 줄이는 매우 효율적인 형태로 구현됩니다.

시작하기

시작하려면 Microsoft.Extensions.Telemetry.Abstractions NuGet 패키지를 설치📦합니다.

dotnet add package Microsoft.Extensions.Telemetry.Abstractions

자세한 내용은 dotnet add package 또는 .NET 애플리케이션에서 패키지 종속성 관리를 참조하세요.

일반 특성

제네릭 특성에는 C# 11 이상이 필요합니다. C# 10 이하의 경우 대신 비제네릭 특성을 사용합니다.

다음 예제에서는 세 개의 메트릭을 선언하는 클래스를 보여 줍니다. 메서드는 특성으로 표시되고 다음과 같이 staticpartial선언됩니다. 코드 생성기는 빌드 시 실행되며 이러한 메서드의 구현과 함께 제공되는 형식을 제공합니다.

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 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 합니다. 메트릭 메서드는 다음으로 제한됩니다.

참고하십시오

지원되는 메트릭에 대한 자세한 내용은 다양한 상황에서 사용할 계 측을 선택하는 방법을 알아보려면 계측 유형을 참조하세요.