Сводка исключений

При попытке создать значимые диагностические сообщения для исключений, поддержание включения соответствующих сведений может быть сложной задачей. Стандартное сообщение об исключении часто не содержит критически важных сведений, которые сопровождают исключение, тогда как вызов метода Exception.ToString приводит к появлению избыточной информации о состоянии.

В этой статье используется пакет NuGet Microsoft.Extensions.Diagnostics.ExceptionSummarization .

Цель суммирования исключений

Теги метрик обычно поддерживают ограниченное количество уникальных значений, поэтому они не подходят для представления значений, которые являются высокой переменной, например результатом Exception.ToString(). Сводка исключений представляет версию сведений об исключении с низкой кардинальностью, которая подходит для таких случаев.

Цель суммирования исключений состоит из двух способов:

  • Чтобы уменьшить кардинальность, связанную с состоянием исключения, так чтобы исключения можно было надежно подсчитывать в метриках. Это имеет значение, так как измерения метрик имеют ограниченную кардинальность.
  • Чтобы удалить конфиденциальную информацию из состояния исключения, чтобы возможность добавить значимую информацию об исключении в журналы сохранялась.

API суммирования исключений

Интерфейс IExceptionSummarizer предлагает методы извлечения важных сведений из распознанных типов исключений, тем самым создавая единственное string значение, которое служит основой для создания высококачественных диагностических сообщений.

Метод IExceptionSummarizer.Summarize систематически проходит по списку зарегистрированных сумматоров, пока он не идентифицирует сумматор, способных обрабатывать конкретный тип исключения. В случае, если средство сводных данных не может распознавать тип исключения, вместо этого предоставляется значимая сводка исключений по умолчанию.

Результат Summarize метода возвращает структуру ExceptionSummary и содержит следующие свойства:

  • ExceptionSummary.Description: краткое описание исключения.
  • ExceptionSummary.AdditionalDetails: предназначено для низкоуровневого диагностирования, это свойство содержит дополнительные сведения об исключении и имеет относительно высокую кардинальность. Это свойство может содержать конфиденциальную информацию.
  • ExceptionSummary.ExceptionType: тип исключения, если внутренние исключения отсутствуют, в этом случае отражаются как внешние, так и внутренние типы.

Пример использования сводки исключений

В следующем примере показано, как использовать IExceptionSummarizer интерфейс для получения сводки исключения.

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

Предыдущий код:

  • Создает новый экземпляр ServiceCollection, последовательно вызывая метод расширения AddExceptionSummarizer.
    • Метод расширения AddExceptionSummarizer принимает делегат, который используется для настройки экземпляра ExceptionSummarizerBuilder.
    • Используется builder для добавления поставщика HTTP, обрабатывающего исключения типа:
  • Создает новый ServiceProvider экземпляр из экземпляра ServiceCollection .
  • Возвращает экземпляр IExceptionSummarizer интерфейса из экземпляра ServiceProvider .
  • Выполняет итерацию по коллекции исключений, вызывая Summarize метод для каждого исключения и отображая результат.

Замечание

Основное внимание в проектировании всех реализаций сводки исключений заключается в том, чтобы обеспечить удобство диагностики, а не приоритет защиты личных сведений (PII). ExceptionSummary.Description не содержит конфиденциальной информации, но ExceptionSummary.AdditionalDetails может содержать такую информацию в зависимости от того, как оно реализовано.

  • Last updated on