Partager via

Résumé d’exception

  • Article

Quand vous essayez de générer des messages de diagnostic explicites pour des exceptions, la gestion de l’inclusion d’informations pertinentes peut poser problème. Le message d’exception standard manque souvent de détails critiques, tandis que l’appel de la méthode Exception.ToString génère un excès d’informations sur l’état.

Cet article s’appuie sur le package NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization.

Objectif du résumé d’exception

Les balises de métrique prennent généralement en charge un nombre limité de valeurs distinctes. Elles ne conviennent donc pas pour représenter des valeurs hautement variables comme le résultat de Exception.ToString(). Un résumé d’exception représente une version à faible cardinalité des informations d’une exception, adaptée à de tels cas.

L’objectif du résumé d’exception est double :

  • Réduire la cardinalité associée à l’état d’exception afin que les exceptions puissent être comptabilisées de manière fiable dans les métriques. Cela est important puisque les dimensions des métriques ont une cardinalité limitée.
  • Éliminer les informations à caractère privé de l’état d’exception afin que certaines informations d’exception explicites puissent être ajoutées aux journaux.

API du résumé d’exception

L’interface IExceptionSummarizer offre des méthodes permettant d’extraire des détails cruciaux à partir de types d’exceptions reconnus, fournissant ainsi une string singulière qui sert de base à l’élaboration de messages de diagnostic de qualité.

La méthode IExceptionSummarizer.Summarize parcourt systématiquement la liste des outils de synthèse d’état inscrits jusqu’à ce qu’elle identifie celui capable de gérer le type d’exception spécifique. Si aucun outil de synthèse d’état n’est capable de reconnaître le type d’exception, un résumé d’exception par défaut explicite est fourni à la place.

Le résultat de la méthode Summarize retourne un struct ExceptionSummary et contient les propriétés suivantes :

  • ExceptionSummary.Description : description du résumé de l’exception.
  • ExceptionSummary.AdditionalDetails : destinée à une utilisation de diagnostic de bas niveau, cette propriété contient des détails supplémentaires sur l’exception et a une cardinalité relativement élevée. Cette propriété peut contenir des informations à caractère privé.
  • ExceptionSummary.ExceptionType : type de l’exception, sauf si des exceptions internes sont présentes, auquel cas les types externe et interne sont reflétés.

Exemple d’utilisation du résumé d’exception

L’exemple suivant montre comment utiliser l’interface IExceptionSummarizer pour récupérer un résumé d’une exception.

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

Le code précédent :

  • Instancie une nouvelle instance ServiceCollection, chaînant un appel à la méthode d’extension AddExceptionSummarizer.
  • Génère une nouvelle instance ServiceProvider à partir de l’instance ServiceCollection.
  • Obtient une instance de l’interface IExceptionSummarizer à partir de l’instance ServiceProvider.
  • Itère une collection d’exceptions, en appelant la méthode Summarize sur chaque exception et en affichant le résultat.

Remarque

L’objectif principal de la conception de toutes les implémentations de résumé d’exception est de faciliter les diagnostics. La priorité n’est donc pas donnée à la protection des informations d’identification personnelle (PII). ExceptionSummary.Description ne contient pas d’informations sensibles, mais ExceptionSummary.AdditionalDetails peut en contenir en fonction de l’implémentation.