异常汇总

尝试为异常生成有意义的诊断消息时，保持包含相关信息可能会带来挑战。 标准异常消息通常缺少与异常相关的关键详细信息，同时调用 Exception.ToString 该方法会产生过多的状态信息。

本文依赖于 Microsoft.Extensions.Diagnostics.ExceptionSummarization NuGet 包。

异常汇总的目标

指标标记通常支持有限数量的非重复值，因此它们不适合表示高度可变的值，例如结果 Exception.ToString()。 异常摘要表示异常信息的低基数版本，适用于此类情况。

异常汇总的目标是双重：

• 减少与异常状态关联的基数，以便可以在指标中可靠地计算异常。 这很重要，因为指标维度的基数有限。
• 从异常状态中消除隐私敏感信息，以便可以向日志添加一些有意义的异常信息。

异常摘要 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 提供程序，该提供程序处理类型异常：
    • OperationCanceledException
    • TaskCanceledException
    • SocketException
    • WebException
• 从ServiceProvider实例生成一个新ServiceCollection实例。
• 从IExceptionSummarizer实例获取ServiceProvider接口的一个实例。
• 循环访问异常集合，对每个异常调用 Summarize 方法并显示结果。