다음을 통해 공유

예외 요약

  • 아티클

예외에 대한 의미 있는 진단 메시지를 생성하려고 할 때 관련 정보를 포함하는 것을 유지하기가 어려울 수 있습니다. 표준 예외 메시지에는 예외와 관련된 중요한 세부 정보가 부족한 경우가 많지만, 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();

앞의 코드가 하는 역할은 다음과 같습니다.

  • AddExceptionSummarizer 확장 메서드에 대한 호출을 연결하여 새 ServiceCollection 인스턴스를 인스턴스화합니다.
  • ServiceCollection 인스턴스에서 새 ServiceProvider 인스턴스를 빌드합니다.
  • ServiceProvider 인스턴스에서 IExceptionSummarizer 인터페이스의 인스턴스를 가져옵니다.
  • 예외 컬렉션을 반복하여 각 예외에 대해 Summarize 메서드를 호출하고 결과를 표시합니다.

참고 항목

모든 예외 요약 구현 디자인에서는 PII(개인 식별 정보) 보호에 우선 순위를 두는 것이 아니라 진단 편의성 제공에 가장 집중해야 합니다. ExceptionSummary.Description에는 중요한 정보가 포함되어 있지 않지만 ExceptionSummary.AdditionalDetails에는 구현에 따라 중요한 정보가 포함될 수 있습니다.