다음을 통해 공유

예외 요약

예외에 대한 의미 있는 진단 메시지를 생성하려는 경우 관련 정보를 포함하는 것을 유지 관리하면 문제가 될 수 있습니다. 표준 예외 메시지에는 예외와 함께 제공되는 중요한 세부 정보가 부족한 경우가 많으며, 메서드를 호출하면 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 확장 메서드를 호출합니다.
  • ServiceProvider 인스턴스에서 새로운 ServiceCollection 인스턴스를 생성합니다.
  • IExceptionSummarizer 인스턴스에서 ServiceProvider 인터페이스의 인스턴스를 가져옵니다.
  • 예외 컬렉션을 반복하여 각 예외에 대해 메서드를 Summarize 호출하고 결과를 표시합니다.

비고

모든 예외 요약 구현 디자인의 주요 초점은 PII(개인 식별 정보) 보호의 우선 순위를 지정하지 않고 진단 편의성을 제공하는 것입니다. 중요한 ExceptionSummary.Description 정보는 포함되지 않지만 ExceptionSummary.AdditionalDetails 구현에 따라 중요한 정보가 포함될 수 있습니다.

  • Last updated on