Riepilogo delle eccezioni

  • Articolo

Quando si tenta di generare messaggi di diagnostica significativi per le eccezioni, assicurarsi che vengano incluse le informazioni pertinenti può rappresentare una sfida. Il messaggio di eccezione standard spesso non contiene dettagli critici che accompagnano l'eccezione, mentre richiamando il metodo Exception.ToString viene restituita una quantità eccessiva di informazioni sullo stato.

Questo articolo si basa sul pacchetto NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization.

Obiettivo del riepilogo delle eccezioni

I tag delle metriche supportano in genere un numero limitato di valori distinti e, di conseguenza, non sono adatti a rappresentare valori altamente variabili, ad esempio il risultato di Exception.ToString(). Un riepilogo delle eccezioni rappresenta una versione con cardinalità bassa delle informazioni di un'eccezione, adatta per tali casi.

L'obiettivo del riepilogo delle eccezioni è duplice:

  • Ridurre la cardinalità associata allo stato di eccezione, in modo che le eccezioni possano essere conteggiate in modo affidabile nelle metriche. Questo aspetto è importante perché le dimensioni delle metriche hanno cardinalità limitata.
  • Eliminare le informazioni sensibili per la privacy dallo stato delle eccezioni, in modo che alcune informazioni significative sulle eccezioni possano essere aggiunte ai log.

API di riepilogo delle eccezioni

L'interfaccia IExceptionSummarizer offre metodi per estrarre dettagli cruciali dai tipi di eccezione riconosciuti, creando così una string unica che funge da base per la creazione di messaggi di diagnostica di alta qualità.

Il metodo IExceptionSummarizer.Summarize attraversa sistematicamente l'elenco di generatori di riepiloghi registrati fino a quando non ne individua uno in grado di gestire il tipo di eccezione specifico. Nel caso in cui nessun generatore di riepilogo sia in grado di riconoscere il tipo di eccezione, viene invece fornito un riepilogo significativo delle eccezioni predefinite.

Il risultato del metodo Summarize restituisce uno struct ExceptionSummary e contiene le proprietà seguenti:

  • ExceptionSummary.Description: descrizione del riepilogo dell'eccezione.
  • ExceptionSummary.AdditionalDetails: destinata all'uso per la diagnostica di basso livello, questa proprietà contiene dettagli aggiuntivi sull'eccezione e ha una cardinalità relativamente elevata. Questa proprietà può contenere informazioni sensibili per la privacy.
  • ExceptionSummary.ExceptionType: tipo di eccezione, a meno che non siano presenti eccezioni interne, nel qual caso viene effettuata la reflection sia dei tipi esterni che di quelli interni.

Esempio di utilizzo del riepilogo delle eccezioni

Nell'esempio seguente viene illustrato come usare l'interfaccia IExceptionSummarizer per recuperare un riepilogo di un'eccezione.

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

Il codice precedente:

  • Viene creata una nuova istanza di ServiceCollection, concatenando una chiamata al metodo di estensione AddExceptionSummarizer.
  • Crea una nuova istanza di ServiceProvider dall'istanza di ServiceCollection.
  • Ottiene un'istanza dell'interfaccia IExceptionSummarizer dall'istanza di ServiceProvider.
  • Esegue l'iterazione su una raccolta di eccezioni, chiamando il metodo Summarize per ogni eccezione e visualizzando il risultato.

Nota

L'obiettivo principale nella progettazione di tutte le implementazioni di riepilogo delle eccezioni è offrire praticità per la diagnostica, invece di dare priorità alla protezione delle informazioni personali (PII). ExceptionSummary.Description non contiene informazioni sensibili, ma ExceptionSummary.AdditionalDetails potrebbe contenere informazioni sensibili a seconda dell'implementazione.