Поделиться через

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

  • Статья

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

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

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

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

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

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

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

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

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

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

  • ExceptionSummary.Description: краткое описание исключения.
  • ExceptionSummary.AdditionalDetails: предназначено для использования низкоуровневой диагностики, это свойство содержит дополнительные сведения об исключении и имеет относительно высокую карта inality. Это свойство может содержать конфиденциальную информацию о конфиденциальности.
  • 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 может содержать конфиденциальную информацию в зависимости от реализации.