Condividi tramite

Riepilogo delle eccezioni

Quando si tenta di generare messaggi di diagnostica significativi per le eccezioni, mantenere l'inclusione di informazioni pertinenti può rappresentare una sfida. Il messaggio di eccezione standard spesso non contiene dettagli critici che accompagnano l'eccezione, mentre richiamando il Exception.ToString metodo viene restituito un eccesso 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 a cardinalità bassa delle informazioni di un'eccezione, adatta per tali casi.

L'obiettivo del riepilogo delle eccezioni è duplice:

  • Per 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.
  • Per eliminare le informazioni sensibili alla 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ì un singolare string che funge da base per la creazione di messaggi di diagnostica di alta qualità.

Il IExceptionSummarizer.Summarize metodo attraversa sistematicamente l'elenco di riepilogatori registrati fino a quando non identifica un summarizer 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 Summarize metodo restituisce uno ExceptionSummary struct e contiene le proprietà seguenti:

  • ExceptionSummary.Description: La descrizione di riepilogo dell'eccezione.
  • ExceptionSummary.AdditionalDetails: destinato all'uso di diagnostica di basso livello, questa proprietà contiene dettagli aggiuntivi sull'eccezione e ha una cardinalità relativamente elevata. Questa proprietà può contenere informazioni riservate alla privacy.
  • ExceptionSummary.ExceptionType: tipo di eccezione, a meno che non siano presenti eccezioni interne, nel qual caso vengono riflesse sia i tipi esterni che 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:

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

Annotazioni

L'obiettivo principale nella progettazione di tutte le implementazioni di riepilogo delle eccezioni consiste nel fornire praticità diagnostica, invece di classificare in ordine di priorità la protezione delle informazioni personali. Il ExceptionSummary.Description, non contiene informazioni riservate, ma il ExceptionSummary.AdditionalDetails potrebbe contenere informazioni riservate a seconda dell'implementazione.

  • Last updated on