.NET でのログサンプリング

.NET には、重要な情報を失うことなく、アプリケーションが出力するログの量を制御できるログサンプリング機能が用意されています。次のサンプリング戦略を使用できます。

トレースベースのサンプリング: 現在のトレースのサンプリング決定に基づくサンプルログ。
ランダム確率的サンプリング: 構成された確率ルールに基づくサンプルログ。
カスタムサンプリング: 独自のカスタムサンプリング戦略を実装します。詳細については、「カスタムサンプリングの実装」を参照してください。

注

一度に使用できるサンプラーは 1 つだけです。複数のサンプラーを登録する場合は、最後のサンプラーが使用されます。

ログサンプリングは、アプリケーションによって出力されるログをより細かく制御できるようにすることで、フィルター機能を拡張します。単にログを有効または無効にする代わりに、サンプリングを構成して、そのごく一部のみを出力することができます。

たとえば、フィルター処理では通常、 0 (ログを出力しない) や 1 (すべてのログの出力) などの確率が使用されますが、サンプリングでは、10% のログを出力する 0.1 や、25%を出力する 0.25 など、任意の値を選択できます。

概要

開始するには、 📦 Microsoft.Extensions.Telemetry NuGet パッケージをインストールします。

.NET CLI
パッケージリファレンス

dotnet add package Microsoft.Extensions.Telemetry

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry"
                    Version="*" />
</ItemGroup>

詳しくは、「dotnet add package」または「.NET アプリケーションでパッケージの依存関係を管理する」をご覧ください。

トレースベースのサンプリングを構成する

トレースベースのサンプリングにより、基になる Activityと一貫してログがサンプリングされます。これは、トレースとログの間の相関関係を維持する場合に便利です。 ( ガイドで説明されているように) トレースサンプリングを有効にし、それに応じてトレースベースのログサンプリングを構成できます。

builder.Logging.AddTraceBasedSampler();

トレースベースのサンプリングを有効にすると、基になる Activity がサンプリングされた場合にのみログが出力されます。サンプリングの決定は、現在の Recorded 値から取得されます。

ランダム確率的サンプリングを構成する

ランダム確率的サンプリングを使用すると、構成された確率ルールに基づいてログをサンプリングできます。特定の条件に対するルールを定義できます:

ログのカテゴリ
ログレベル
イベント ID

規則を使用してランダム確率的サンプリングを構成するには、いくつかの方法があります。

ファイルベースの構成

appsettings.jsonに構成セクションを作成します。次に例を示します。

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },

  "RandomProbabilisticSampler": {
    "Rules": [
      {
        "CategoryName": "Microsoft.AspNetCore.*",
        "Probability": 0.25,
        "LogLevel": "Information"
      },
      {
        "CategoryName": "System.*",
        "Probability": 0.1
      },
      {
        "EventId": 1001,
        "Probability": 0.05
      }
    ]
  }
}

上記の構成:

すべてのレベルの System. から始まるカテゴリからのログのサンプル 10%。
Microsoft.AspNetCore.のLogLevel.Informationから始まるカテゴリのログを25%サンプリング。
すべてのカテゴリとレベルからイベント ID が 1001 のログのうち5%をサンプルします。
他のすべてのログを100%サンプリングします。

Important

Probability値は、0 から 1 までの値を持つ確率を表します。たとえば、0.25 は、25% のログがサンプリングされることを意味します。 0 はログがサンプリングされないことを意味し、1 はすべてのログがサンプリングされることを意味します。 0 と 1 の場合は、特定のルールのすべてのログを効果的に無効または有効にするために使用できます。確率を 0 未満または 1 より大きくすることはできません。このエラーがアプリケーションで発生した場合は、例外がスローされます。

サンプラーを構成に登録するには、次のコードを検討します。

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

実行中のアプリでサンプリング規則を変更する

ランダム確率的サンプリングでは、 IOptionsMonitor<TOptions> インターフェイスを介したランタイム構成の更新がサポートされます。ファイル構成プロバイダーなどの再読み込みをサポートする構成プロバイダーを使用している場合は、アプリケーションを再起動せずに実行時にサンプリング規則を更新できます。

たとえば、no-opとして効果的に機能する次の appsettings.jsonを使用してアプリケーションを起動できます。

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 1
        }
      ]
    }
  }
}

アプリの実行中に、次の構成で appsettings.json を更新できます。

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 0.01,
          "LogLevel": "Information"
        }
      ]
    }
  }
}

上記の構成など、新しい規則が自動的に適用され、 LogLevel.Information を含む 1% のログがサンプリングされます。

サンプリングルールの適用方法

このアルゴリズムはログフィルター処理とよく似ていますが、いくつかの違いがあります。

ログサンプリングルールの評価は各ログレコードで実行されますが、キャッシュなどのパフォーマンスの最適化が行われています。特定のカテゴリのログレコードごとに、次のアルゴリズムが使用されます。

ロガーのログレベルと同等またはそれ以上のLogLevel規則を選択します。
定義されていないか、あるいは定義されており、ログイベントIDと等しいルールを選択します。
一致するカテゴリプレフィックスが最も長いルールを選択します。一致が見つからない場合は、カテゴリを指定しないすべての規則が選択されます。
複数の規則が選択されている場合は、最後の 1 つが使用されます。
ルールが選択されていない場合、サンプリングは適用されません。たとえば、ログレコードは通常どおりに出力されます。

インラインコードの構成

builder.Logging.AddRandomProbabilisticSampler(options =>
{
    options.Rules.Add(
        new RandomProbabilisticSamplerFilterRule(
            probability: 0.05d,
            eventId : 1001));
});

上記の構成:

すべてのカテゴリとレベルからイベント ID が 1001 のログのうち5%をサンプルします。
他のすべてのログを100%サンプリングします。

単純な確率構成

基本的なシナリオでは、指定したレベル以下のすべてのログに適用される単一の確率値を構成できます。

builder.Logging.AddRandomProbabilisticSampler(0.01, LogLevel.Information);
builder.Logging.AddRandomProbabilisticSampler(0.1, LogLevel.Warning);

上記のコードは、 Warning ログの 10% と 1% の Information (以下) のログをサンプリングするサンプラーを登録します。構成に Informationの規則がない場合は、 Warning ログの 10% と、以下のすべてのレベル ( Information を含む) がサンプリングされます。

カスタムサンプリングを実装する

LoggingSampler抽象クラスから派生し、その抽象メンバーをオーバーライドすることで、カスタムサンプリング戦略を作成できます。これにより、特定の要件に合わせてサンプリング動作を調整できます。たとえば、カスタムサンプラーは次の場合があります。

ログ状態の特定のキーと値のペアの存在と値に基づいて、サンプリングの決定を行います。
定義済みの時間間隔内のログの数が特定のしきい値を下回っている場合にのみログを出力するなど、レート制限ロジックを適用します。

カスタムサンプラーを実装するには、次の手順に従います。

LoggingSamplerから継承するクラスを作成します。
LoggingSampler.ShouldSample メソッドをオーバーライドして、カスタムサンプリングロジックを定義します。
AddSampler拡張メソッドを使用して、カスタムサンプラーをログパイプラインに登録します。

フィルター処理されていないログレコードごとに、 LoggingSampler.ShouldSample メソッドは 1 回だけ呼び出されます。その戻り値は、ログレコードを出力する必要があるかどうかを決定します。

パフォーマンスに関する考慮事項

ログサンプリングは、ストレージコストを削減するように設計されており、CPU 使用率がわずかに増加するトレードオフがあります。アプリケーションで大量のログが生成され、保存コストが高い場合、サンプリングはそのボリュームを減らすのに役立ちます。適切に構成すると、インシデントの診断に不可欠な情報を失うことなく、サンプリングによってストレージコストを削減できます。

組み込みのサンプリングについては、「ベンチマーク」を参照してください。

サンプリングを使用するタイミングに関するログレベルガイダンス

ログレベル	勧告
Trace	通常は運用環境でこれらのログを無効にするため、サンプリングを適用しないでください
Debug	通常は運用環境でこれらのログを無効にするため、サンプリングを適用しないでください
Information	サンプリングを適用する
Warning	サンプリングの適用を検討する
Error	サンプリングを適用しない
Critical	サンプリングを適用しない

ベストプラクティス

より高いサンプリングレートから始め、必要に応じて下方向に調整します。
カテゴリベースのルールを使用して、特定のコンポーネントをターゲットにします。
分散トレースを使用している場合は、トレースベースのサンプリングを実装することを検討してください。
サンプリングルールの有効性をまとめて監視します。
アプリケーションに適したバランスを見つけます。サンプリングレートが低すぎると可観測性が低下し、レートが高すぎるとコストが増加する可能性があります。

こちらも参照ください

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-02-05

次の方法で共有

.NET でのログ サンプリング

概要

トレース ベースのサンプリングを構成する

ランダム確率的サンプリングを構成する

ファイルベースの構成

実行中のアプリでサンプリング 規則を変更する

サンプリング ルールの適用方法

インライン コードの構成