异常汇总

尝试为异常生成有意义的诊断消息时，保持包含相关信息可能面临挑战。 标准异常消息通常缺少与异常相关的关键详细信息，同时，调用 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
• 基于 ServiceCollection 实例构建一个新的 ServiceProvider 实例。
• 从 ServiceProvider 实例获取 IExceptionSummarizer 接口的实例。
• 循环访问异常集合，对每个异常调用 Summarize 方法并显示结果。

注意

所有异常汇总实现设计的主要重点是提供诊断便利性，而不是优先保护个人身份信息 (PII)。 ExceptionSummary.Description 不包含敏感信息，但 ExceptionSummary.AdditionalDetails 可能会包含敏感信息，具体取决于实现。