ASP.NET Core 메트릭

메트릭은 시간에 따라 보고된 숫자 측정값입니다. 이를 사용하여 앱의 상태를 모니터링하고 경고를 생성합니다. 예를 들어, 웹 서비스는 다음 수를 추적할 수 있습니다.

• 초당 수신하는 요청입니다.
• 응답하는 데 걸리는 시간(밀리초)입니다.
• 오류와 함께 보내는 응답입니다.

이러한 메트릭을 정기적으로 모니터링 시스템에 보고합니다. 메트릭을 보고 사용자에게 문제를 알리는 경고를 만들도록 대시보드를 설정합니다. 웹 서비스가 400ms 이내의 요청에 응답하고 600ms에서 응답을 시작하는 경우 모니터링 시스템은 운영 직원에게 앱 응답이 정상보다 느리다는 것을 알릴 수 있습니다.

특성과 함께 모든 계측의 포괄적인 목록은 ASP.NET Core 기본 제공 메트릭에 설명되어 있습니다.

메트릭 사용

메트릭을 사용하려면 다음이 포함됩니다.

• 계측: .NET 라이브러리의 코드는 측정을 수행하여 이러한 측정값을 메트릭 이름과 연결합니다. .NET 및 ASP.NET Core에는 많은 기본 제공 메트릭이 포함됩니다.
• 컬렉션 및 스토리지: .NET 앱은 외부 스토리지 및 분석을 위해 앱에서 전송되도록 명명된 메트릭을 구성합니다. 일부 도구는 구성 파일 또는 UI 도구를 사용하여 앱 외부에서 구성을 수행할 수 있습니다.
• 시각화: 사람이 읽을 수 있는 형식으로 메트릭을 표시할 수 있는 도구입니다. 예를 들어 Grafana 및 Prometheus입니다.
• 경고: 메트릭이 임계값을 초과할 때 알림을 제공하는 도구입니다. 예를 들어 웹 서비스의 평균 응답 시간이 400ms를 초과하면 운영 직원에게 경고를 보낼 수 있습니다.
• 분석: 시간에 따라 메트릭을 분석할 수 있는 도구입니다. 이 도구는 특정 앱에 대한 가장 중요한 메트릭을 표시하도록 사용자 지정할 수 있는 웹 기반 대시보드인 경우가 많습니다.

계측된 코드는 숫자 측정값을 기록할 수 있지만 모니터링에 유용한 메트릭을 만들려면 측정값을 집계, 전송 및 저장해야 합니다. 데이터를 모아서 전송하고 저장하는 과정을 컬렉션이라고 합니다. 이 자습서에서는 메트릭을 수집하고 표시하는 몇 가지 예를 보여 줍니다.

• OpenTelemetry 및 Prometheus를 사용하여 Grafana에서 메트릭 채우기
• dotnet-counters를 사용하여 실시간으로 메트릭 보기

분석을 위해 데이터를 분류할 수 있는 태그라는 키-값 쌍과 측정값을 연결할 수도 있습니다. 자세한 내용은 다차원 메트릭을 참조 하세요.

시작 앱 만들기

다음 명령을 사용하여 새 ASP.NET Core 앱을 만듭니다.

dotnet new web -o WebMetric
cd WebMetric
dotnet add package OpenTelemetry.Exporter.Prometheus.AspNetCore --prerelease
dotnet add package OpenTelemetry.Extensions.Hosting

Program.cs의 내용을 다음 코드로 바꿉니다.

using OpenTelemetry.Metrics;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddOpenTelemetry()
    .WithMetrics(builder =>
    {
        builder.AddPrometheusExporter();

        builder.AddMeter("Microsoft.AspNetCore.Hosting",
                         "Microsoft.AspNetCore.Server.Kestrel");
        builder.AddView("http.server.request.duration",
            new ExplicitBucketHistogramConfiguration
            {
                Boundaries = new double[] { 0, 0.005, 0.01, 0.025, 0.05,
                       0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 }
            });
    });
var app = builder.Build();

app.MapPrometheusScrapingEndpoint();

app.MapGet("/", () => "Hello OpenTelemetry! ticks:"
                     + DateTime.Now.Ticks.ToString()[^3..]);

app.Run();

dotnet-counters를 사용하여 메트릭 보기

dotnet-counters 는 요청 시 .NET 앱에 대한 라이브 메트릭을 볼 수 있는 명령줄 도구입니다. 설정이 필요하지 않으므로 임시 조사나 메트릭 계측이 작동하는지 확인하는 데 유용합니다. System.Diagnostics.Metrics 기반 API 및 EventCounters 모두에서 작동합니다.

dotnet-counters 도구가 설치되지 않은 경우 다음 명령을 실행합니다.

dotnet tool update -g dotnet-counters

테스트 앱이 실행되는 동안 dotnet-counters를 시작 합니다. 다음 명령은 dotnet-counters의 모든 메트릭을 모니터링하는 예시를 보여 줍니다.

dotnet-counters monitor -n WebMetric --counters Microsoft.AspNetCore.Hosting

다음과 비슷한 출력이 표시됩니다.

Press p to pause, r to resume, q to quit.
    Status: Running

[Microsoft.AspNetCore.Hosting]
    http-server-current-requests
        host=localhost,method=GET,port=5045,scheme=http                    0
    http-server-request-duration (s)
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0.001
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0
        host=localhost,method=GET,port=5045,protocol=HTTP/1.1,ro           0

자세한 내용은 dotnet-counters를 참조하세요.

ASP.NET Core 요청 메트릭 보강

ASP.NET Core에는 많은 기본 제공 메트릭이 있습니다. 메트릭: http.server.request.duration

• 서버에서 HTTP 요청의 기간을 기록합니다.
• 일치하는 경로 및 응답 상태 코드와 같은 요청 정보를 태그로 캡처합니다.

http.server.request.duration 메트릭은 IHttpMetricsTagsFeature를 사용하여 태그 보강을 지원합니다. 보강은 라이브러리 또는 앱이 자체 태그를 메트릭에 추가하는 경우입니다. 이 기능은 앱이 메트릭을 사용하여 빌드된 대시보드 또는 경고에 사용자 지정 분류를 추가하려는 경우에 유용합니다.

using Microsoft.AspNetCore.Http.Features;

var builder = WebApplication.CreateBuilder();
var app = builder.Build();

app.Use(async (context, next) =>
{
    var tagsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (tagsFeature != null)
    {
        var source = context.Request.Query["utm_medium"].ToString() switch
        {
            "" => "none",
            "social" => "social",
            "email" => "email",
            "organic" => "organic",
            _ => "other"
        };
        tagsFeature.Tags.Add(new KeyValuePair<string, object?>("mkt_medium", source));
    }

    await next.Invoke();
});

app.MapGet("/", () => "Hello World!");

app.Run();

위의 예제는 다음과 같습니다.

• 미들웨어를 추가하여 ASP.NET Core 요청 메트릭을 보강합니다.
• [IHttpMetricsTagsFeature]에서 [HttpContext]를 가져옵니다. 이 기능은 누군가가 메트릭을 수신 대기하는 경우에만 컨텍스트에 있습니다. 사용하기 전에 null이(가) IHttpMetricsTagsFeature이(가) 아닌지 확인하세요.
• 요청의 마케팅 원본이 포함된 사용자 지정 태그를 메트릭에 http.server.request.duration 추가합니다.
  • 태그에는 utm_medium 쿼리 문자열 값을 기반으로 mkt_medium 이름과 값이 있습니다. utm_medium 값은 알려진 값 범위로 결정됩니다.
  • 태그를 사용하면 웹앱 트래픽을 분석할 때 유용할 수 있는 마케팅 중간 유형별로 요청을 분류할 수 있습니다.

비고

사용자 지정 태그를 사용하여 보강할 때 다차원 메트릭 모범 사례를 따릅니다. 너무 많거나 언바운드 범위가 있는 태그는 많은 태그 조합을 만들어 높은 차원을 생성합니다. 컬렉션 도구는 카운터에 대해 지원되는 차원에 제한이 있으며 과도한 메모리 사용을 방지하기 위해 결과를 필터링할 수 있습니다.

특정 엔드포인트 및 요청에서 HTTP 메트릭 옵트아웃

메트릭 기록 옵트아웃은 상태 검사와 같은 자동화된 시스템에서 자주 호출하는 엔드포인트에 유용합니다. 이러한 요청에 대한 메트릭을 기록하는 것은 일반적으로 필요하지 않습니다. 원치 않는 원격 분석은 리소스를 사용하여 수집 및 저장하며 원격 분석 대시보드에 표시되는 결과를 왜곡할 수 있습니다.

DisableHttpMetrics 특성 또는 DisableHttpMetrics 메서드를 사용하여 메타데이터를 추가하여 메트릭에서 엔드포인트에 대한 HTTP 요청을 제외할 수 있습니다.

• DisableHttpMetrics 특성을 Web API 컨트롤러, SignalR 허브 또는 gRPC 서비스에 추가합니다.
• 앱 시작 시 엔드포인트를 매핑할 때 DisableHttpMetrics를 호출합니다.

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHealthChecks();

var app = builder.Build();
app.MapHealthChecks("/healthz").DisableHttpMetrics();
app.Run();

또는 다음을 위해 IHttpMetricsTagsFeature.MetricsDisabled 속성이 추가되었습니다:

• 요청이 엔드포인트에 매핑되지 않는 고급 시나리오입니다.
• 특정 HTTP 요청에 대한 메트릭 컬렉션을 동적으로 사용하지 않도록 설정

// Middleware that conditionally opts-out HTTP requests.
app.Use(async (context, next) =>
{
    var metricsFeature = context.Features.Get<IHttpMetricsTagsFeature>();
    if (metricsFeature != null &&
        context.Request.Headers.ContainsKey("x-disable-metrics"))
    {
        metricsFeature.MetricsDisabled = true;
    }

    await next(context);
});

사용자 지정 메트릭 만들기

System.Diagnostics.Metrics 네임스페이스에서 API를 사용하여 메트릭을 생성합니다. 자세한 내용은 사용자 지정 메트릭 만들기를 참조하세요.

를 사용하여 ASP.NET Core 앱에서 메트릭 만들기 IMeterFactory

IMeterFactory를 사용하여 ASP.NET Core 앱에서 Meter 인스턴스를 만듭니다.

ASP.NET Core는 IMeterFactory 기본적으로 DI(종속성 주입)에 등록됩니다. 미터 팩터리는 메트릭을 DI와 통합하여 메트릭을 쉽게 격리하고 수집할 수 있습니다. IMeterFactory 는 테스트에 특히 유용합니다. 여러 테스트를 나란히 실행할 수 있으며 테스트에 기록된 메트릭 값만 수집합니다.

앱에서 사용 IMeterFactory 하려면 앱의 사용자 지정 메트릭을 만드는 데 사용하는 IMeterFactory 형식을 만듭니다.

public class ContosoMetrics
{
    private readonly Counter<int> _productSoldCounter;

    public ContosoMetrics(IMeterFactory meterFactory)
    {
        var meter = meterFactory.Create("Contoso.Web");
        _productSoldCounter = meter.CreateCounter<int>("contoso.product.sold");
    }

    public void ProductSold(string productName, int quantity)
    {
        _productSoldCounter.Add(quantity,
            new KeyValuePair<string, object?>("contoso.product.name", productName));
    }
}

다음에서 DI를 사용하여 메트릭 형식을 등록합니다.Program.cs

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<ContosoMetrics>();

필요한 경우 메트릭 형식 및 레코드 값을 삽입합니다. 메트릭 형식은 DI에 등록되므로 MVC 컨트롤러, 최소 API 또는 DI에서 만든 다른 형식과 함께 사용할 수 있습니다.

app.MapPost("/complete-sale", (SaleModel model, ContosoMetrics metrics) =>
{
    // ... business logic such as saving the sale to a database ...

    metrics.ProductSold(model.ProductName, model.QuantitySold);
});

"Contoso.Web" 미터를 모니터링하려면 다음 dotnet-counters 명령을 사용합니다.

dotnet-counters monitor -n WebMetric --counters Contoso.Web

다음과 비슷한 출력이 표시됩니다.

Press p to pause, r to resume, q to quit.
    Status: Running

[Contoso.Web]
    contoso.product.sold (Count / 1 sec)
        contoso.product.name=Eggs            12    
        contoso.product.name=Milk            0    

OpenTelemetry 및 Prometheus를 사용하여 Grafana에서 메트릭 보기

Overview

OpenTelemetry:

• Cloud Native Computing Foundation에서 지원하는 공급업체 중립적 오픈 소스 프로젝트입니다.
• 클라우드 기반 소프트웨어에 대한 원격 분석 생성 및 수집을 표준화합니다.
• .NET 메트릭 API를 사용하여 .NET에서 작동합니다.
• Azure Monitor 및 많은 APM 공급업체의 보증을 받았습니다.

이 자습서에서는 OSS Prometheus 및 Grafana 프로젝트를 사용하여 OpenTelemetry 메트릭에 사용할 수 있는 통합 중 하나를 보여 줍니다. 메트릭 데이터 흐름:

1. ASP.NET Core 메트릭 API는 예제 앱의 측정값을 기록합니다.

2. 앱에서 실행되는 OpenTelemetry .NET 라이브러리는 측정값을 집계합니다.

3. Prometheus exporter 라이브러리는 HTTP 메트릭 엔드포인트를 통해 집계된 데이터를 사용할 수 있게 합니다. 'Exporter'는 OpenTelemetry가 공급업체별 백 엔드에 원격 분석을 전송하는 라이브러리를 지칭하는 용어입니다.

4. Prometheus 서버:

   • 메트릭 엔드포인트를 주기적으로 조회합니다.
   • 데이터를 읽습니다.
   • 장기간 지속성을 위해 데이터를 데이터베이스에 저장합니다. Prometheus는 엔드포인트를 스크래핑하는 것으로 데이터를 읽고 저장하는 것을 말합니다.
   • 다른 컴퓨터에서 실행할 수 있습니다.

5. Grafana 서버:

   • Prometheus에 저장된 데이터를 쿼리하여 웹 기반 모니터링 대시보드에 표시합니다.
   • 다른 컴퓨터에서 실행할 수 있습니다.

샘플 앱에서 메트릭 보기

샘플 앱으로 이동합니다. 브라우저에는 가 표시되며, 여기서 3digits는 현재 Hello OpenTelemetry! ticks:<3digits>의 마지막 세 자리입니다.

URL에 /metrics를 추가하여 메트릭 엔드포인트를 확인하십시오. 브라우저에 수집되는 메트릭이 표시됩니다.

Prometheus 설정 및 구성

Prometheus 첫 번째 단계에 따라 Prometheus 서버를 설정하고 작동 중인지 확인합니다.

Prometheus가 예제 앱이 노출하는 메트릭 엔드포인트를 긁어내도록 prometheus.yml 구성 파일을 수정합니다. scrape_configs 섹션에 다음 강조 표시된 텍스트를 추가합니다.

# my global config
global:
  scrape_interval: 15s # Set the scrape interval to every 15 seconds. Default is every 1 minute.
  evaluation_interval: 15s # Evaluate rules every 15 seconds. The default is every 1 minute.
  # scrape_timeout is set to the global default (10s).

# Alertmanager configuration
alerting:
  alertmanagers:
    - static_configs:
        - targets:
          # - alertmanager:9093

# Load rules once and periodically evaluate them according to the global 'evaluation_interval'.
rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

# A scrape configuration containing exactly one endpoint to scrape:
# Here it's Prometheus itself.
scrape_configs:
  # The job name is added as a label `job=<job_name>` to any timeseries scraped from this config.
  - job_name: "prometheus"

    # metrics_path defaults to '/metrics'
    # scheme defaults to 'http'.

    static_configs:
      - targets: ["localhost:9090"]

  - job_name: 'MyASPNETApp'
    scrape_interval: 5s # Poll every 5 seconds for a more responsive demo.
    static_configs:
      - targets: ["localhost:5045"]  ## Enter the HTTP port number of the demo app.

앞서 강조 표시된 YAML에서 5045를 예제 앱에서 사용하는 포트 번호로 바꾸세요.

Prometheus를 시작하세요

1. 구성을 다시 로드하거나 Prometheus 서버를 다시 시작합니다.
2. Prometheus 웹 포털의 상태>대상 페이지에서 OpenTelemetryTest가 UP 상태인지 확인합니다.

메트릭 탐색기 열기 아이콘을 선택하여 사용 가능한 메트릭을 확인합니다.

사용 가능한 메트릭을 확인하려면 http_ 입력 상자에 와 같은 카운터 범주를 입력합니다.

또는 사용 가능한 메트릭을 확인하려면 kestrel 입력 상자에 와 같은 카운터 범주를 입력합니다:

Grafana 대시보드에 메트릭 표시

• 설치 지침에 따라 Grafana를 설치하고 Prometheus 데이터 원본에 연결합니다.

• Prometheus 그래프 만들기를 따르세요. 또는 .NET 메트릭용 미리 빌드된 대시보드를 .NET 팀 대시보드 @ grafana.com 다운로드할 수 있습니다. 다운로드한 대시보드 JSON을 Grafana로 가져올 수 있습니다.

ASP.NET Core 앱에서 메트릭 테스트

ASP.NET Core 앱에서 메트릭을 테스트할 수 있습니다. 이를 위한 한 가지 방법은 ASP.NET Core 통합 테스트에서 메트릭 값을 수집하고 MetricCollector<T>를 사용해 검증하는 것입니다.

public class BasicTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly WebApplicationFactory<Program> _factory;
    public BasicTests(WebApplicationFactory<Program> factory) => _factory = factory;

    [Fact]
    public async Task Get_RequestCounterIncreased()
    {
        // Arrange
        var client = _factory.CreateClient();
        var meterFactory = _factory.Services.GetRequiredService<IMeterFactory>();
        var collector = new MetricCollector<double>(meterFactory,
            "Microsoft.AspNetCore.Hosting", "http.server.request.duration");

        // Act
        var response = await client.GetAsync("/");

        // Assert
        Assert.Contains("Hello OpenTelemetry!", await response.Content.ReadAsStringAsync());

        await collector.WaitForMeasurementsAsync(minCount: 1).WaitAsync(TimeSpan.FromSeconds(5));
        Assert.Collection(collector.GetMeasurementSnapshot(),
            measurement =>
            {
                Assert.Equal("http", measurement.Tags["url.scheme"]);
                Assert.Equal("GET", measurement.Tags["http.request.method"]);
                Assert.Equal("/", measurement.Tags["http.route"]);
            });
    }
}

이전 테스트:

• WebApplicationFactory<TEntryPoint>를 사용하여 메모리에서 웹앱을 부트스트랩합니다. Program 팩터리의 제네릭 인수에서 웹앱을 지정합니다.
• 를 사용하여 메트릭 값을 수집합니다. MetricCollector<T>
  • 필요한 패키지 참조는 Microsoft.Extensions.Diagnostics.Testing 입니다.
  • 웹 앱의 MetricCollector<T>는 IMeterFactory를 사용하여 생성됩니다. 이렇게 하면 수집기에서 테스트에 의해 기록된 메트릭 값만 보고할 수 있습니다.
  • 수집할 미터 이름 Microsoft.AspNetCore.Hosting및 카운터 이름을 http.server.request.duration 포함합니다.
• 웹앱에 대한 HTTP 요청을 만듭니다.
• 메트릭 수집기의 결과를 사용하여 테스트를 어설션합니다.

ASP.NET Core Identity 지표

Identity ASP.NET Core 관찰성을 통해 사용자 관리 활동 및 인증 프로세스를 모니터링할 수 있습니다.

메트릭은 Microsoft.AspNetCore.Identity 미터로 측정되며, 다음 섹션에서 설명됩니다.

사용자 관리 메트릭

• aspnetcore.identity.user.create.duration 는 사용자 만들기 작업의 기간을 측정합니다.
• aspnetcore.identity.user.update.duration 는 사용자 업데이트 작업의 기간을 측정합니다.
• aspnetcore.identity.user.delete.duration 는 사용자 삭제 작업의 기간을 측정합니다.
• aspnetcore.identity.user.check_password_attempts 은 암호 확인 시도를 계산합니다.
• aspnetcore.identity.user.generated_tokens 는 암호 재설정 토큰과 같이 사용자에 대해 생성된 토큰을 계산합니다.
• aspnetcore.identity.user.verify_token_attempts 는 토큰 확인 시도를 계산합니다.

인증 메트릭

• aspnetcore.identity.sign_in.authenticate.duration 는 인증 작업 기간을 측정합니다.
• aspnetcore.identity.sign_in.check_password_attempts 는 로그인하는 동안 암호 검사 시도를 계산합니다.
• aspnetcore.identity.sign_in.sign_ins 는 성공적인 로그인을 계산합니다.
• aspnetcore.identity.sign_in.sign_outs 는 로그아웃 수를 계산합니다.
• aspnetcore.identity.sign_in.two_factor_clients_remembered 는 2단계 클라이언트를 기억했습니다.
• aspnetcore.identity.sign_in.two_factor_clients_forgotten 는 잊혀진 2단계 인증 클라이언트를 세고 있습니다.

다음 메트릭을 사용하여 다음을 수행합니다.

• 사용자 등록 및 관리를 모니터링합니다.
• 인증 패턴 및 잠재적인 보안 문제를 추적합니다.
• Identity 작업의 성능을 측정합니다.
• 2단계 인증 사용량을 관찰합니다.

메트릭 보기 Identity

이러한 메트릭을 보고 실시간으로 모니터링하는 데 사용합니다 dotnet-counters . 또는 이 문서의 앞부분에서 설명한 기술을 사용하여 Prometheus로 내보내고 Grafana에서 시각화합니다.

예를 들어 다음을 사용하여 모든 Identity 메트릭을 모니터링합니다.dotnet-counters

dotnet-counters monitor -n YourAppName --counters Microsoft.AspNetCore.Identity

ASP.NET Core 미터 및 카운터

ASP.NET Core 미터 및 카운터 목록은 ASP.NET Core 메트릭을 참조하세요. ASP.NET Core 11 이상에서는 기본 제공 HTTP 서버 미터(예: Microsoft.AspNetCore.Hosting 및Microsoft.AspNetCore.Server.Kestrel)가 OpenTelemetry HTTP 서버 의미 체계 규칙의 필수 부분을 준수하는 데이터를 내보낸다. OpenTelemetry SDK를 사용하면 OpenTelemetry.Instrumentation.AspNetCore 패키지 없이도 이러한 미터를 사용할 수 있습니다.