.NET および .NET Core でのカスタムメトリックの収集

[アーティクル]
01/31/2024

Azure Monitor Application Insights の .NET および .NET Core SDK には、カスタムメトリックを収集する 2 つの異なるメソッド (TrackMetric() と GetMetric()) があります。これら 2 つのメソッドの主な違いは、ローカル集計です。 TrackMetric() メソッドには事前集計がありません。 GetMetric() メソッドには事前集計があります。集計を使用することをお勧めします。そのため、TrackMetric() はカスタムメトリックを収集するための推奨される方法ではなくなりました。この記事では、GetMetric() メソッドの使用方法と、そのしくみの背後にある論理的根拠についていくつか説明します。

Note

以下のドキュメントは、Application Insights クラシック API に関するものです。 Application Insights の長期的な計画は、OpenTelemetry を使用してデータを収集することです。詳しくは、「.NET、Node.js、Python、Java アプリケーション用の Azure Monitor OpenTelemetry を有効にする」をご覧ください。

事前集計 API と非事前集計 API

TrackMetric() メソッドでは、メトリックを示す未加工のテレメトリを送信します。値ごとに単一のテレメトリ項目を送信することは、非効率的です。また、すべての TrackMetric(item) がテレメトリ初期化子とプロセッサの完全な SDK パイプラインを通過するため、TrackMetric() メソッドはパフォーマンスの点でも非効率的です。

TrackMetric() とは異なり、GetMetric() ではローカル事前集計が自動的に処理され、1 分の一定間隔で集計されたサマリーメトリックのみが送信されます。一部のカスタムメトリックを秒またはミリ秒単位で厳密に監視する必要がある場合、1 分ごとに監視するだけのストレージとネットワークトラフィックのコストのみが発生している間にそのようにすることができます。また、この動作により、集計されたメトリックに対して送信する必要があるテレメトリ項目の合計数が大幅に減少するため、調整が発生するリスクが大幅に軽減されます。

Application Insights では、TrackMetric() と GetMetric() を介して収集されたカスタムメトリックはサンプリングの対象にはなりません。重要なメトリックをサンプリングすると、これらのメトリックに基づいて作成した可能性のあるアラートの信頼性が低下する場合があるシナリオにつながることがあります。カスタムメトリックをサンプリングしないようにすることで、一般に、アラートのしきい値違反が発生した場合にアラートが起動するという確信を得ることができます。カスタムメトリックはサンプリングされないため、潜在的な懸念事項がいくつかあります。

1 秒ごとに、あるいはさらに細かい間隔でメトリックの傾向を追跡すると、次のようになることがあります。

データストレージのコストが増加する。 Azure Monitor に送信するデータの量に関連したコストが発生します送信するデータの量が多いほど、監視の全体的なコストが高くなります。
ネットワークトラフィックまたはパフォーマンスのオーバーヘッドが増加します。 一部のシナリオでは、このオーバーヘッドにより、金銭的にもアプリケーションパフォーマンスの面でもコストがかかる可能性があります。
インジェスト調整のリスク アプリで短期間に高いレートのテレメトリを送信すると、Azure Monitor によってデータポイントが削除 ("スロットル") されます。

調整が懸念事項になるのは、それによってアラートが起動しなくなる場合があるためです。アラートをトリガーする条件がローカルで発生し、送信されるデータが多すぎるためにインジェストエンドポイントで削除される可能性があります。独自のローカル集計ロジックを実装していない限り、.NET および .NET Core では TrackMetric() を使用しないことをお勧めします。すべてのインスタンスを追跡しようとしたときに、特定の期間にわたってイベントが発生した場合は、TrackEvent() の方が適していることがわかります。カスタムメトリックとは異なり、カスタムイベントはサンプリングの対象となることに注意してください。独自のローカル事前集計を記述しなくても TrackMetric() を引き続き使用することはできます。ただし、その場合は落とし穴に注意してください。

つまり、事前集計を行い、すべての Track() 呼び出しからの値を蓄積し、1 分ごとにサマリーや集計を送信するという理由から、GetMetric() を推奨します。 GetMetric() メソッドにより、すべての関連情報を引き続き収集しながら、送信するデータポイントを少なくすることによって、コストとパフォーマンスのオーバーヘッドを大幅に削減できます。

注意

GetMetric() メソッドがあるのは、.NET および .NET Core SDK のみです。 Java を使用している場合は、Micrometer を使用したカスタムメトリックの送信に関するセクションを参照してください。 JavaScript と Node.js の場合は、引き続き TrackMetric() を使用しますが、前のセクションで概説した注意事項に留意してください。 Python の場合は、OpenCensus.stats を使用してカスタムメトリックを送信できますが、メトリックの実装は異なります。

GetMetric の使用を開始する

この例では、基本的な .NET Core 3.1 ワーカーサービスアプリケーションを使用します。これらの例で使用されたテスト環境をレプリケートする場合は、ワーカーサービスの監視に関する記事の手順 1 から 6 に従います。次の手順では、基本的な worker サービスプロジェクトテンプレートに Application Insights を追加します。この概念は、Web アプリやコンソールアプリを含め、SDK を使用できる一般的なアプリケーションに適用されます。

メトリックの送信

worker.cs ファイルの内容を次のコードに置き換えます。

using System;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Microsoft.ApplicationInsights;

namespace WorkerService3
{
    public class Worker : BackgroundService
    {
        private readonly ILogger<Worker> _logger;
        private TelemetryClient _telemetryClient;

        public Worker(ILogger<Worker> logger, TelemetryClient tc)
        {
            _logger = logger;
            _telemetryClient = tc;
        }

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {   // The following line demonstrates usages of GetMetric API.
            // Here "computersSold", a custom metric name, is being tracked with a value of 42 every second.
            while (!stoppingToken.IsCancellationRequested)
            {
                _telemetryClient.GetMetric("ComputersSold").TrackValue(42);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(1000, stoppingToken);
            }
        }
    }
}

サンプルコードを実行すると、Visual Studio 出力ウィンドウにテレメトリが送信されることなく、while ループが繰り返し実行されていることがわかります。単一のテレメトリ項目が約 60 秒のマークで送信され、このテストでは次のようになります。

Application Insights Telemetry: {"name":"Microsoft.ApplicationInsights.Dev.00000000-0000-0000-0000-000000000000.Metric", "time":"2019-12-28T00:54:19.0000000Z",
"ikey":"00000000-0000-0000-0000-000000000000",
"tags":{"ai.application.ver":"1.0.0.0",
"ai.cloud.roleInstance":"Test-Computer-Name",
"ai.internal.sdkVersion":"m-agg2c:2.12.0-21496",
"ai.internal.nodeName":"Test-Computer-Name"},
"data":{"baseType":"MetricData",
"baseData":{"ver":2,"metrics":[{"name":"ComputersSold",
"kind":"Aggregation",
"value":1722,
"count":41,
"min":42,
"max":42,
"stdDev":0}],
"properties":{"_MS.AggregationIntervalMs":"42000",
"DeveloperMode":"true"}}}}

この単一のテレメトリ項目は、41 の個別のメトリック測定の集計を表します。同じ値を何度も送信していたため、標準偏差 (stDev) は 0 で、最大 (max) と最小 (min) の値は同一になっています。 value プロパティは、集計されたすべての個別の値の合計を表します。

注意

GetMetric メソッドでは、最後の値 (例: gauge) の追跡や、ヒストグラムまたは分布の追跡はサポートされていません。

ログ (Analytics) エクスペリエンスで Application Insights リソースを調べると、個別のテレメトリ項目は次のスクリーンショットのようになります。

Note

取り込み後に未加工のテレメトリ項目に明示的な sum プロパティやフィールドは含まれませんが、ここでは 1 つ作成します。この場合、value と valueSum の両方のプロパティは同じことを表します。

ログベースとカスタムメトリックの両方として、ポータルの [メトリック] セクションでカスタムメトリックテレメトリにアクセスすることもできます。次のスクリーンショットはログベースのメトリックの例です。

高スループット使用率のメトリック参照をキャッシュする

場合によっては、メトリック値が頻繁に観測されることがあります。たとえば、1 秒あたり 500 要求を処理する高スループットサービスでは、要求ごとに 20 個のテレメトリメトリックの生成が必要になる場合があります。結果は、1 秒あたり 10,000 の値を追跡することを意味します。このような高スループットのシナリオでは、ユーザーは、一部の参照を回避して SDK を補助することが必要になる場合があります。

たとえば、前の例では、ComputersSold というメトリックのハンドルを参照し、観測値 42 を追跡しました。代わりに、複数のトラック呼び出しに対してハンドルがキャッシュされる可能性があります。

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is where the cache is stored to handle faster lookup
            Metric computersSold = _telemetryClient.GetMetric("ComputersSold");
            while (!stoppingToken.IsCancellationRequested)
            {

                computersSold.TrackValue(42);

                computersSold.TrackValue(142);

                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

前の例では、メトリックハンドルをキャッシュするだけでなく、Task.Delay も 50 ミリ秒に短縮され、ループがより頻繁に実行されるようになりました。その結果、TrackValue() が 772 回呼び出されました。

多次元メトリック

前のセクションの例は、0 次元メトリックを示しています。メトリックは多次元にすることもできます。現在、最大で 10 個のディメンションがサポートされています。

1 次元メトリックを作成する方法の例を次に示します。

//...

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            // This is an example of a metric with a single dimension.
            // FormFactor is the name of the dimension.
            Metric computersSold= _telemetryClient.GetMetric("ComputersSold", "FormFactor");

            while (!stoppingToken.IsCancellationRequested)
            {
                // The number of arguments (dimension values)
                // must match the number of dimensions specified while GetMetric.
                // Laptop, Tablet, etc are values for the dimension "FormFactor"
                computersSold.TrackValue(42, "Laptop");
                computersSold.TrackValue(20, "Tablet");
                computersSold.TrackValue(126, "Desktop");


                _logger.LogInformation("Worker running at: {time}", DateTimeOffset.Now);
                await Task.Delay(50, stoppingToken);
            }
        }

このサンプルコードを少なくとも 60 秒実行すると、3 つの異なるテレメトリ項目が Azure に送信されます。それぞれの項目は、3 つのフォームファクターのいずれかの集計を表します。先ほどと同じように、ログ (Analytics) ビューでさらに確認することができます。

メトリックスエクスプローラーでは、次のようになります。

新しいカスタムディメンションでメトリックを分割したり、メトリックビューでカスタムディメンションを表示したりできないことがわかります。

既定では、メトリックエクスプローラー内の多次元メトリックは、Application Insights リソースで有効になっていません。

多次元メトリックを有効にする

Application Insights リソースに対して多次元メトリックを有効にするには、[使用量と推定コスト]>[カスタムメトリック]>[カスタムメトリックディメンションに関するアラートを有効にします]>[OK] の順に選択します。詳細については、「カスタムメトリックのディメンションと事前集計」を参照してください。

この変更を行って新しい多次元テレメトリを送信した後、[分割を適用] を選択できます。

Note

ポータルで機能をオンにした後に新しく送信されたメトリックにのみ、ディメンションが格納されます。

各 FormFactor ディメンションのメトリック集計を表示します。

3 個を超えるディメンションがある場合に MetricIdentifier を使用する

現在、10 個のディメンションがサポートされています。 3 個を超えるディメンションでは MetricIdentifier を使用する必要があります。

// Add "using Microsoft.ApplicationInsights.Metrics;" to use MetricIdentifier
// MetricIdentifier id = new MetricIdentifier("[metricNamespace]","[metricId],"[dim1]","[dim2]","[dim3]","[dim4]","[dim5]");
MetricIdentifier id = new MetricIdentifier("CustomMetricNamespace","ComputerSold", "FormFactor", "GraphicsCard", "MemorySpeed", "BatteryCapacity", "StorageCapacity");
Metric computersSold  = _telemetryClient.GetMetric(id);
computersSold.TrackValue(110,"Laptop", "Nvidia", "DDR4", "39Wh", "1TB");

カスタムメトリックの構成

メトリックの構成を変更する場合は、メトリックが初期化されている場所で変更を行う必要があります。

特殊なディメンション名

メトリックでは、アクセスに使われる TelemetryClient のテレメトリコンテキストは使用されません。 MetricDimensionNames クラスの定数として有効である特殊なディメンション名の使用は、このような制限がある場合に最適な回避策です。

次の Special Operation Request Size メトリックによって送信されたメトリック集計では、Context.Operation.Name が Special Operation に設定されません。 TrackMetric() メソッドやその他の TrackXXX() メソッドでは、OperationName が Special Operation に正しく設定されます。

        //...
        TelemetryClient specialClient;
        private static int GetCurrentRequestSize()
        {
            // Do stuff
            return 1100;
        }
        int requestSize = GetCurrentRequestSize()

        protected override async Task ExecuteAsync(CancellationToken stoppingToken)
        {
            while (!stoppingToken.IsCancellationRequested)
            {
                //...
                specialClient.Context.Operation.Name = "Special Operation";
                specialClient.GetMetric("Special Operation Request Size").TrackValue(requestSize);
                //...
            }
                   
        }

この場合、TelemetryContext 値を指定するために、MetricDimensionNames クラスに一覧表示されている特殊なディメンション名を使用します。

たとえば、次のステートメントの結果として得られるメトリック集計が Application Insights クラウドエンドポイントに送信されると、その Context.Operation.Name データフィールドは Special Operation に設定されます。

_telemetryClient.GetMetric("Request Size", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation");

この特殊なディメンションの値は TelemetryContext にコピーされ、"通常の" ディメンションとしては使用されません。通常のメトリック探索のために操作ディメンションも保持する場合は、その目的のために別のディメンションを作成する必要があります。

_telemetryClient.GetMetric("Request Size", "Operation Name", MetricDimensionNames.TelemetryContext.Operation.Name).TrackValue(requestSize, "Special Operation", "Special Operation");

ディメンションと時系列の上限

テレメトリサブシステムで誤ってリソースを使い切らないようにするために、メトリックごとのデータ系列の最大数を制御できます。既定の制限は、メトリックごとのデータ系列の合計が 1,000 を超えず、ディメンションごとの異なる値が 100 を超えないことです。

重要

調整を回避するには、ディメンションに使用する基数の値を小さくします。

ディメンションと時系列の上限のコンテキストでは、Metric.TrackValue(..) を使用して、制限が観測されていることを確認します。制限に既に達している場合、Metric.TrackValue(..) により False が返され、値は追跡されません。それ以外の場合は、 Trueを返します。この動作は、メトリックのデータがユーザー入力によって生じる場合に便利です。

MetricConfiguration コンストラクターでは、各メトリック内のさまざまな系列を管理する方法に関するいくつかのオプションを使用します。また、メトリックの個々の系列に対して集計動作を指定する IMetricSeriesConfiguration を実装するクラスのオブジェクトを使用します。

var metConfig = new MetricConfiguration(seriesCountLimit: 100, valuesPerDimensionLimit:2,
                new MetricSeriesConfigurationForMeasurement(restrictToUInt32Values: false));

Metric computersSold = _telemetryClient.GetMetric("ComputersSold", "Dimension1", "Dimension2", metConfig);

// Start tracking.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value1");
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value2");

// The following call gives 3rd unique value for dimension2, which is above the limit of 2.
computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3");
// The above call does not track the metric, and returns false.

seriesCountLimit は、メトリックに含めることができるデータ時系列の最大数です。この制限に達すると、TrackValue() が呼び出されます。この結果、通常、新しい系列によって false が返されます。
valuesPerDimensionLimit では、同じようにディメンションごとに個別の値の数を制限します。
restrictToUInt32Values では、負でない整数値のみを追跡するかどうかを決定します。

上限を超えているかどうかを確認するためのメッセージを送信する方法の例を以下に示します。

if (! computersSold.TrackValue(100, "Dim1Value1", "Dim2Value3"))
{
// Add "using Microsoft.ApplicationInsights.DataContract;" to use SeverityLevel.Error
_telemetryClient.TrackTrace("Metric value not tracked as value of one of the dimension exceeded the cap. Revisit the dimensions to ensure they are within the limits",
SeverityLevel.Error);
}

次のステップ

メトリック - Get - REST API
カスタムのイベントとメトリックのための Application Insights API
ワーカーサービスアプリケーションの監視の詳細については、こちらを参照してください。
ログベースの事前に集計されたメトリックを使用します。
メトリックスエクスプローラーでメトリックを分析します。
ASP.NET Core アプリケーション用の Application Insights を有効にする方法を学びます。
ASP.NET アプリケーション用の Application Insights を有効にする方法を学びます。

.NET および .NET Core でのカスタム メトリックの収集

事前集計 API と非事前集計 API

GetMetric の使用を開始する

メトリックの送信

高スループット使用率のメトリック参照をキャッシュする

多次元メトリック

多次元メトリックを有効にする

3 個を超えるディメンションがある場合に MetricIdentifier を使用する

カスタム メトリックの構成

特殊なディメンション名

ディメンションと時系列の上限

次のステップ

その他のリソース

.NET および .NET Core でのカスタムメトリックの収集

カスタムメトリックの構成