Partilhar via

Sumarização de exceções

  • Artigo

Quando você está tentando gerar mensagens de diagnóstico significativas para exceções, manter a inclusão de informações pertinentes pode representar um desafio. A mensagem de exceção padrão geralmente não possui detalhes críticos que acompanham a exceção, enquanto invocar o Exception.ToString método produz um excesso de informações de estado.

Este artigo depende do pacote NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization .

O objetivo da sumarização de exceções

As tags métricas normalmente suportam um número limitado de valores distintos e, como tal, não são adequadas para representar valores que são altamente variáveis, como o resultado de Exception.ToString(). Um resumo de exceção representa uma versão de baixa cardinalidade das informações de uma exceção, adequada para esses casos.

O objetivo da sumarização de exceções é duplo:

  • Para reduzir a cardinalidade associada ao estado de exceção, de modo que as exceções possam ser contadas de forma confiável em métricas. Isto é importante, uma vez que as dimensões métricas têm cardinalidade limitada.
  • Para eliminar informações confidenciais de privacidade do estado de exceção, de modo que algumas informações de exceção significativas possam ser adicionadas aos logs.

API de resumo de exceção

A IExceptionSummarizer interface oferece métodos para extrair detalhes cruciais de tipos de exceção reconhecidos, fornecendo assim um singular string que serve como base para a elaboração de mensagens de diagnóstico de alta qualidade.

O IExceptionSummarizer.Summarize método percorre sistematicamente a lista de resumos registrados até identificar um resumidor capaz de lidar com o tipo de exceção específico. Caso nenhum resumidor seja capaz de reconhecer o tipo de exceção, um resumo de exceção padrão significativo é fornecido.

O resultado do Summarize método retorna um ExceptionSummary struct e contém as seguintes propriedades:

  • ExceptionSummary.Description: A descrição sumária da exceção.
  • ExceptionSummary.AdditionalDetails: Destinada ao uso de diagnóstico de baixo nível, esta propriedade contém detalhes adicionais sobre a exceção e tem uma cardinalidade relativamente alta. Esta propriedade pode conter informações confidenciais de privacidade.
  • ExceptionSummary.ExceptionType: O tipo de exceção, a menos que existam exceções internas, caso em que os tipos externo e interno são refletidos.

Exemplo de uso de resumo de exceção

O exemplo a seguir demonstra como usar a IExceptionSummarizer interface para recuperar um resumo de uma exceção.

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();

O código anterior:

  • Instancia uma nova ServiceCollection instância, encadeando uma chamada para o AddExceptionSummarizer método de extensão.
  • Cria uma nova ServiceProvider instância a partir da ServiceCollection instância.
  • Obtém uma instância da IExceptionSummarizer interface da ServiceProvider instância.
  • Itera sobre uma coleção de exceções, chamando o Summarize método em cada exceção e exibindo o resultado.

Nota

O foco principal no design de todas as implementações de resumo de exceção é fornecer conveniência de diagnóstico, em vez de priorizar a proteção de informações pessoalmente identificáveis (PII). O ExceptionSummary.Description não contém informações confidenciais, mas o ExceptionSummary.AdditionalDetails pode conter informações confidenciais, dependendo da implementação.