次の方法で共有

例外の要約

例外に対して意味のある診断メッセージを生成しようとすると、関連する情報を含め維持することが困難な場合があります。 標準の例外メッセージには、例外に付随する重要な詳細がないことがよくありますが、 Exception.ToString メソッドを呼び出すと、過剰な状態情報が生成されます。

この記事では、 Microsoft.Extensions.Diagnostics.ExceptionSummarization NuGet パッケージに依存しています。

例外要約の目標

メトリック タグは通常、限られた数の個別の値をサポートするため、 Exception.ToString()の結果など、非常に可変の値を表すには適していません。 例外の概要は、このような場合に適した、例外の情報のカーディナリティが低いバージョンを表します。

例外の要約の目的は、次の 2 つです。

  • メトリックで例外を確実にカウントできるように、例外状態に関連付けられているカーディナリティを減らします。 メトリック ディメンションのカーディナリティが制限されているため、これは重要です。
  • 重要な例外情報をログに追加できるように、プライバシーに関する機密情報を例外状態から排除します。

例外要約のAPI

IExceptionSummarizer インターフェイスは、認識された例外の種類から重要な詳細を抽出する方法を提供します。これにより、最高品質の診断メッセージを作成するための基盤として機能する単一のstringが提供されます。

IExceptionSummarizer.Summarizeメソッドは、特定の例外の種類を処理できるサマライザーを識別するまで、登録済みサマライザーの名簿を体系的に走査します。 サマライザーが例外の種類を認識できない場合は、代わりに意味のある既定の例外の概要が提供されます。

Summarize メソッドの結果は、ExceptionSummary構造体を返し、次のプロパティが含まれています。

  • ExceptionSummary.Description: 例外の概要の説明。
  • ExceptionSummary.AdditionalDetails: 低レベルの診断を目的としたこのプロパティには、例外に関する追加の詳細が含まれており、カーディナリティが比較的高くなります。 このプロパティには、プライバシーに関する機密情報が含まれている場合があります。
  • ExceptionSummary.ExceptionType:内部例外が存在しない限り、例外の型。その場合、外側と内側の両方の型が反映されます。

例外要約の使用例

次の例では、 IExceptionSummarizer インターフェイスを使用して例外の概要を取得する方法を示します。

using System.Net;
using System.Net.Sockets;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Diagnostics.ExceptionSummarization;

// Add exception summarization services.
var services = new ServiceCollection()
    .AddExceptionSummarizer(static builder => builder.AddHttpProvider());

var provider = services.BuildServiceProvider();

// Get the exception summarizer.
IExceptionSummarizer summarizer = provider.GetRequiredService<IExceptionSummarizer>();

// Define exceptions to summarize.
Exception[] exceptions =
[
    new OperationCanceledException("Operation cancelled..."),
    new TaskCanceledException("Task cancelled..."),
    new SocketException(10_024, "Too many sockets open..."),
    new WebException("Keep alive failure...",
        WebExceptionStatus.KeepAliveFailure)
];

foreach (var exception in exceptions)
{
    // Summarize the exception.
    ExceptionSummary summary = summarizer.Summarize(exception);

    Console.WriteLine(summary);
}

Console.ReadLine();

前述のコード:

  • 新しい ServiceCollection インスタンスをインスタンス化し、 AddExceptionSummarizer 拡張メソッドの呼び出しをチェーンします。
  • ServiceProvider インスタンスから新しいServiceCollection インスタンスをビルドします。
  • IExceptionSummarizer インスタンスからServiceProvider インターフェイスのインスタンスを取得します。
  • 例外のコレクションを反復処理し、各例外で Summarize メソッドを呼び出し、結果を表示します。

注

すべての例外要約実装の設計における主な焦点は、個人を特定できる情報 (PII) の保護を優先するのではなく、診断の利便性を提供することです。 ExceptionSummary.Descriptionには機密情報は含まれませんが、ExceptionSummary.AdditionalDetailsには実装によっては機密情報が含まれる場合があります。

  • Last updated on