ASP.NET Core のメトリクス

メトリックは、時間の経過に伴って報告される数値測定値です。 アプリの正常性を監視し、アラートを生成するために使用します。 例えば、あるウェブ サービスが、数量を追跡するなどです。

• 1 秒あたりに受け取るリクエスト
• 応答に要するミリ秒。
• エラー時に送信される応答。

これらのメトリックを一定の間隔で監視システムに報告します。 メトリックを表示し、問題をユーザーに通知するアラートを作成するためのダッシュボードを設定します。 ウェブ サービスが 400 ミリ秒以内にリクエストに応答することを意図しているのに、600 ミリ秒で応答し始めた場合、監視システムは、アプリの応答が通常より遅いことを運用担当者に通知します。

すべてのインストルメントとその属性の包括的な一覧については、組み込みのメトリック ASP.NET Core説明されています。

メトリックを使用する

メトリックスに使用には次が含まれます。

• インストルメンテーション: .NET ライブラリのコードによって、測定値が取得され、これらの測定値がメトリック名に関連付けられます。 .NET および ASP.NET Core には、複数の組み込みメトリックが含まれています。
• コレクションおよびストレージ: .NET アプリは、外部ストレージおよび分析のためにアプリから送信する必要のある名前付きメトリックを構成します。 一部のツールでは、構成ファイルまたは UI ツールを使用して、アプリの外部で構成を実行する場合があります。
• ビジュアル化: 人間が読める形式でメトリックを表示するツール。 たとえば、Aspireダッシュボード、Grafana、Prometheus。
• アラート: メトリックがしきい値を超えたときに通知を提供するツール。 たとえば、あるウェブ サービスの平均応答時間が 400 ミリ秒を超えた場合、運用担当者にアラートを送信できます。
• 分析: メトリックを経時的に分析できるツール。 このツールは、多くの場合、特定のアプリの最も重要なメトリックを表示するようにカスタマイズできる Web ベースのダッシュボードです。

インストルメント化されたコードでは数値の測定値を記録できますが、監視に役立つメトリックを作成するには、測定値を集計、送信、格納する必要があります。 このようなデータの集計、送信、格納のプロセスは収集と呼ばれます。 このチュートリアルでは、メトリックの収集と表示の例をいくつか示します。

• OpenTelemetry と Prometheus を使って Grafana のメトリックを設定します。
• dotnet-countersを使用してメトリックをリアルタイムで表示する。

別の視覚化オプションについては、 Aspire ダッシュボードの概要を参照してください。

また、測定をタグと呼ばれるキーと値のペアに関連付けて、分析用のデータを分類することもできます。 詳細については、「多次元メトリック」を参照してください。

スターター アプリを作成する

次のコマンドを使用して、新しい 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からのすべてのメトリックを監視する Microsoft.AspNetCore.Hosting の例を示しています。

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 を取得します。 この機能は、誰かがメトリックをリッスンしている場合にのみ、コンテキスト上に存在します。 使用する前に、 IHttpMetricsTagsFeature が null されていないことを確認します。
• http.server.request.duration メトリックにリクエストのマーケティング ソースを含むカスタム タグを追加します。
  • このタグは mkt_medium という名前と、utm_medium というクエリ文字列の値に基づいた値を保持しています。 utm_medium 値は、既知の値の範囲に解決されます。
  • このタグは、リクエストをマーケティング媒体のタイプ別に分類することができ、Web アプリのトラフィックを分析する際に役立ちます。

Note

カスタム タグを強化する場合は、多次元メトリック のベスト プラクティスに従います。 タグの数が多すぎたり、範囲に縛りがなかったりすると、タグの組み合わせが多くなり、ディメンションが大きくなります。 コレクション ツールでは、カウンターでサポートされているディメンションに制限があり、メモリの過剰な使用を防ぐために結果をフィルター処理する場合があります。

特定のエンドポイントと要求で 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 を使用して作成します。 詳細については、「 カスタム メトリックの作成」を参照してください。

IMeterFactory を使用して ASP.NET Core アプリでメトリックを作成する

IMeterFactoryを使用 ASP.NET CoreアプリにMeter インスタンスを作成します。

ASP.NET Core は、デフォルトで、dependency injection (DI) に IMeterFactory を登録します。 測定ファクトリは、メトリックを 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));
    }
}

Program.cs の DI を使用してメトリック型を登録する:

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 がサポートする vendor-neutral open-source プロジェクトです。
• クラウドネイティブ ソフトウェアのテレメトリの生成と収集を標準化します。
• .NET metric API を使用して .NET で動作します。
• Azure Monitor や多くの APM ベンダーに支持されています。

このチュートリアルは、OSS Prometheus と Grafana の各プロジェクトを使った OpenTelemetry メトリックに現在使うことができる統合の 1 つを示しています。 メトリック データ フロー:

1. ASP.NET Core metric API は、サンプル アプリからの測定を記録します。

2. アプリで実行中の OpenTelemetry .NET ライブラリは、測定を集計します。

3. Prometheus エクスポーター ライブラリにより、集計されたデータを HTTP メトリック エンドポイント経由で使うことができるようになります。 'エクスポーター' とは、ベンダー固有のバックエンドにテレメトリを送信するライブラリに OpenTelemetry が付けた名称です。

4. Prometheus サーバー:

   • メトリクス エンドポイントを定期的に問い合わせます。
   • データを読み取ります。
   • 長期保存のためにデータをデータベースに保存します。 Prometheus は、データの読み取りと保存を、エンドポイントのスクレイピングと呼んでいます。
   • 異なるマシンで実行できます。

5. Grafana サーバー:

   • Prometheus に保存されているデータをクエリし、Web ベースのモニタリング ダッシュボードに表示します。
   • 異なるマシンで実行できます。

サンプル プリからのメトリックを表示する

サンプル アプリに移動します。 ブラウザーには、3digitsが現在の DateTime.Ticks の最後の 3 桁であるHello OpenTelemetry! ticks:<3digits>が表示されます。

/metrics を URL に追加して、メトリック エンドポイントを表示します。 ブラウザは、収集されたメトリックを表示します。

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. OpenTelemetryTest が、Prometheus Web ポータルの [状態]>、[ターゲット] ページの UP 状態になっているかを確認します。

[メトリック エクスプローラーを開く] アイコンを選択して、利用可能なメトリックを表示します。

[式] 入力ボックスにhttp_などのカウンター カテゴリを入力して、使用可能なメトリックを表示します。

または、[式] 入力ボックスにkestrelなどのカウンター カテゴリを入力して、使用可能なメトリックを表示します。

Grafana ダッシュボードにメトリックを表示する

• インストール手順に従って Grafana をインストールし、Prometheus のデータソースに接続します。

• 「Prometheus グラフを作成する」に従います。 また、.NET メトリック用の事前構築済みダッシュボードは、.NET team dashboards @ grafana.com でダウンロードできます。 ダウンロードした ダッシュボード JSON は、Grafana にインポートできます。

ASP.NET Core アプリでメトリックをテストする

ASP.NET Core アプリでメトリックをテストできます。 これを行う 1 つの方法は、MetricCollector<T>を使用して、ASP.NET Core統合テストでメトリック値を収集してアサートすることです。

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> を使用してメモリで Web アプリをブートストラップします。 ファクトリーのジェネリック引数の Program は、Web アプリを指定します。
• MetricCollector<T> を使用してメトリック値を収集する
  • Microsoft.Extensions.Diagnostics.Testingへのパッケージ参照が必要です。
  • MetricCollector<T> は、Web アプリの IMeterFactory を使用して作成します。 これにより、コレクターは、テストが記録したメトリック値のみをレポートします。
  • 収集する 測定名 Microsoft.AspNetCore.Hosting とカウンター名 http.server.request.duration を含めます。
• Web アプリで HTTP リクエストを行います。
• メトリック コレクターからの結果を使用してテストをアサートします。

ASP.NET Core Identity メトリック

ASP.NET Core Identity可観測性は、ユーザー管理アクティビティと認証プロセスを監視するのに役立ちます。

メトリックは 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 コア測定とカウンター

ASP.NET Coreメーターとカウンターの一覧については、ASP.NET Coreメトリックを参照してください。 ASP.NET Core 11 以降では、組み込みの HTTP サーバー メーター (たとえば、Microsoft.AspNetCore.HostingやMicrosoft.AspNetCore.Server.Kestrel) は、OpenTelemetry HTTP サーバーセマンティック規則の必要な部分に準拠するデータを出力します。 これらのメーターは、 OpenTelemetry.Instrumentation.AspNetCore パッケージなしで OpenTelemetry SDK で使用できます。

その他のリソース

• Aspire ダッシュボードの概要
• テレメトリを Aspire 調べる
• ASP.NET Core の組み込みメトリック