Compartilhar via

Resumo de exceção

  • 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 tem detalhes críticos que acompanham a exceção, enquanto invocar o método Exception.ToString gera um excesso de informações de estado.

Este artigo se baseia no pacote NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization.

A meta de resumo de exceção

As marcas de métrica normalmente dão suporte a 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.

A meta de resumo de exceção é dupla:

  • 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. Isso importa, pois as dimensões de métrica 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ções

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

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

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

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

Exemplo de uso de resumo de exceção

O exemplo a seguir demonstra como usar a interface IExceptionSummarizer 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:

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

Observação

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