例外の要約
例外に対して意味のある診断メッセージを生成しようとすると、関連する情報を含めることを維持することが困難な場合があります。 標準の例外メッセージには、多くの場合、例外に付随する重要な詳細が欠けていますが、Exception.ToString メソッドを呼び出すと、過剰な状態情報が生成されます。
この記事は、Microsoft.Extensions.Diagnostics.ExceptionSummarization NuGet パッケージに依存しています。
例外要約の目標
メトリック タグは通常、限られた数の個別の値をサポートするため、Exception.ToString() の結果など、大きく異なる値を表すには適していません。 例外の概要は、このような場合に適した、例外の情報のカーディナリティ バージョンを表します。
例外要約の目標は、次の twofold です。
- 例外をメトリックで確実にカウントできるように、例外の状態に関連付けられているカーディナリティを減らします。 これは、メトリック ディメンションのカーディナリティが限られているため重要です。
- 重要な例外情報をログに追加できるように、プライバシーに関するプライバシーに関する機密情報を例外状態から排除します。
例外要約 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 拡張メソッドへの呼び出しをチェーンします。
AddExceptionSummarizer拡張メソッドは、ExceptionSummarizerBuilderインスタンスの構成に使用されるデリゲートを受け入れます。builderは、次の型の例外を処理する HTTP プロバイダーを追加するために使用されます。
ServiceCollectionインスタンスから新しいServiceProviderインスタンスを構築します。ServiceProviderインスタンスからIExceptionSummarizerインターフェイスのインスタンスを取得します。- 例外のコレクションを反復処理し、各例外で
Summarizeメソッドを呼び出し、結果を表示します。
Note
すべての例外要約実装の設計における主な焦点は、個人を特定できる情報 (PII) の保護を優先することではなく、診断の利便性を提供することです。 ExceptionSummary.Description に機密情報は含まれませんが、実装によっては ExceptionSummary.AdditionalDetails に機密情報が含まれる場合があります。
.NET