Resumen de excepciones

Cuando se intenta generar mensajes de diagnóstico significativos para excepciones, mantener la inclusión de información pertinente puede suponer un desafío. El mensaje de excepción estándar a menudo carece de detalles críticos que acompañan a la excepción, mientras que la invocación del método Exception.ToString produce un exceso de información de estado.

Este artículo se basa en el paquete NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization.

Objetivo del resumen de excepciones

Normalmente, las etiquetas de métrica admiten un número limitado de valores distintos y, como tal, no son adecuados para representar valores que son muy variables, como el resultado de Exception.ToString(). Un resumen de excepciones representa una versión de cardinalidad baja de la información de una excepción, adecuada para estos casos.

El objetivo del resumen de excepciones es dos veces:

• Para reducir la cardinalidad asociada con el estado de excepción, de modo que las excepciones se puedan contar de forma confiable en las métricas. Esto importa, ya que las dimensiones de las métricas tienen una cardinalidad limitada.
• Para eliminar la información confidencial de privacidad del estado de excepción, de modo que se pueda agregar información significativa de excepciones a los registros.

API de resumen de excepciones

La interfaz IExceptionSummarizer ofrece métodos para extraer detalles cruciales de los tipos de excepción reconocidos, lo que proporciona un singular string que sirve como base para elaborar mensajes de diagnóstico de alta calidad.

El método IExceptionSummarizer.Summarize recorre sistemáticamente la lista de resumidores registrados hasta que identifica un resumidor capaz de manejar el tipo de excepción específico. En caso de que ningún generador de resumen sea capaz de reconocer el tipo de excepción, se proporciona en su lugar un resumen de excepciones predeterminado significativo.

El resultado del método Summarize devuelve una estructura ExceptionSummary y contiene las siguientes propiedades:

• ExceptionSummary.Description: descripción de resumen de la excepción.
• ExceptionSummary.AdditionalDetails: diseñado para el uso de diagnóstico de bajo nivel, esta propiedad contiene detalles adicionales sobre la excepción y tiene una cardinalidad relativamente alta. Esta propiedad puede contener información confidencial de privacidad.
• ExceptionSummary.ExceptionType: el tipo de la excepción, a menos que haya excepciones internas presentes, en cuyo caso se reflejan los tipos externos y internos.

Ejemplo de uso de resumen de excepciones

En el ejemplo siguiente se muestra cómo usar la interfaz IExceptionSummarizer para recuperar un resumen de una excepción.

C#

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

El código anterior:

• Crea instancias de una nueva instancia de ServiceCollection, encadenando una llamada al método de extensión AddExceptionSummarizer.
  • El método de extensión AddExceptionSummarizer acepta un delegado que se usa para configurar la instancia de ExceptionSummarizerBuilder.
  • El builder se usa para agregar el proveedor HTTP, que controla las excepciones de tipo:
    • OperationCanceledException
    • TaskCanceledException
    • SocketException
    • WebException
• Compila una nueva instancia de ServiceProvider a partir de la instancia de ServiceCollection.
• Obtiene una instancia de la interfaz de IExceptionSummarizer de la instancia de ServiceProvider.
• Recorre en iteración una colección de excepciones, llamando al método Summarize en cada excepción y mostrando el resultado.

Nota

El enfoque principal en el diseño de todas las implementaciones de resumen de excepciones es brindar conveniencia de diagnóstico, en lugar de priorizar la protección de la información de identificación personal (PII). El ExceptionSummary.Description no contiene información confidencial, pero el ExceptionSummary.AdditionalDetails puede contener información confidencial en función de la implementación.