Udostępnij za pośrednictwem

Podsumowanie wyjątków

  • Artykuł

Podczas próby wygenerowania znaczących komunikatów diagnostycznych dla wyjątków utrzymanie odpowiednich informacji może stanowić wyzwanie. Standardowy komunikat o wyjątku często nie zawiera krytycznych szczegółów towarzyszących wyjątkowi, podczas gdy wywołanie Exception.ToString metody daje nadmiar informacji o stanie.

Ten artykuł opiera się na pakiecie NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization .

Cel podsumowania wyjątków

Tagi metryk zwykle obsługują ograniczoną liczbę unikatowych wartości i w związku z tym nie są odpowiednie do reprezentowania wartości, które są wysoce zmienne, takie jak wynik .Exception.ToString() Podsumowanie wyjątku reprezentuje wersję o niskiej kardynalności informacji o wyjątku, odpowiednią dla takich przypadków.

Celem podsumowania wyjątków jest dwa razy:

  • Aby zmniejszyć kardynalność skojarzona ze stanem wyjątku, tak aby wyjątki można było niezawodnie liczyć w metrykach. Ma to znaczenie, ponieważ wymiary metryki mają ograniczoną kardynalność.
  • Aby wyeliminować informacje poufne prywatności ze stanu wyjątku, tak aby niektóre istotne informacje o wyjątkach można było dodać do dzienników.

Interfejs API podsumowania wyjątków

Interfejs IExceptionSummarizer oferuje metody wyodrębniania kluczowych szczegółów z rozpoznanych typów wyjątków, a tym samym wyposażenie pojedynczej string jednostki, która służy jako podstawa do tworzenia najwyższej jakości komunikatów diagnostycznych.

Metoda IExceptionSummarizer.Summarize systematycznie przechodzi przez skład zarejestrowanych składników podsumowania, dopóki nie zidentyfikuje sumatora, który może obsługiwać określony typ wyjątku. W przypadku, gdy żaden składnik podsumowania nie może rozpoznać typu wyjątku, zamiast tego zostanie podane znaczące domyślne podsumowanie wyjątków.

Wynik Summarize metody zwraca ExceptionSummary strukturę i zawiera następujące właściwości:

  • ExceptionSummary.Description: opis podsumowania wyjątku.
  • ExceptionSummary.AdditionalDetails: Przeznaczony do użycia diagnostycznego niskiego poziomu, ta właściwość zawiera dodatkowe szczegóły dotyczące wyjątku i ma stosunkowo wysoką kardynalność. Ta właściwość może zawierać informacje poufne dla prywatności.
  • ExceptionSummary.ExceptionType: Typ wyjątku, chyba że istnieją wyjątki wewnętrzne, w którym są odzwierciedlone zarówno typy zewnętrzne, jak i wewnętrzne.

Przykładowe użycie podsumowania wyjątków

W poniższym przykładzie pokazano, jak używać interfejsu IExceptionSummarizer do pobierania podsumowania wyjątku.

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

Powyższy kod ma następujące działanie:

  • Tworzy wystąpienie nowego ServiceCollection wystąpienia, łącząc wywołanie AddExceptionSummarizer metody rozszerzenia.
  • Tworzy nowe ServiceProvider wystąpienie z ServiceCollection wystąpienia.
  • Pobiera wystąpienie interfejsu IExceptionSummarizerServiceProvider z wystąpienia.
  • Iteruje kolekcję wyjątków, wywołując metodę Summarize dla każdego wyjątku i wyświetlając wynik.

Uwaga

Głównym celem projektowania wszystkich implementacji podsumowania wyjątków jest zapewnienie wygody diagnostycznej, a nie priorytetyzacja ochrony danych osobowych (PII). Element ExceptionSummary.Description nie zawiera informacji poufnych, ale ExceptionSummary.AdditionalDetails może zawierać poufne informacje w zależności od implementacji.