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

Выборка логов в .NET

.NET предоставляет возможности выборки журналов, которые позволяют управлять объемом журналов, которые приложение выдает без потери важных сведений. Доступны следующие стратегии выборки:

  • Выборка на основе трассировки: примеры журналов на основе решения выборки текущей трассировки.
  • Случайная вероятностная выборка: отбор журналов на основе настроенных правил вероятности.
  • Настраиваемая выборка: реализуйте собственную стратегию выборки. Дополнительные сведения см. в разделе "Реализация пользовательской выборки".

Замечание

Одновременно можно использовать только один самплер. Если вы регистрируете несколько образцов, используется последний.

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

Например, при фильтрации обычно используются вероятности, такие как 0 (не выпускать журналы) или 1 (выпустить все журналы), выборка позволяет выбрать любое значение (между) — например, 0.1 вывести 10% журналов или 0.25 выпустить 25%.

Начало работы

Чтобы приступить к работе, установите 📦 пакет NuGet Microsoft.Extensions.Telemetry :

dotnet add package Microsoft.Extensions.Telemetry

Дополнительные сведения см. в разделе dotnet add package или Управление зависимостями пакетов в приложениях .NET.

Настройка выборки на основе трассировки

Выборка на основе трассировки гарантирует, что журналы выборки осуществляются согласованно с базовыми Activity. Это полезно при сохранении корреляции между трассировками и журналами. Вы можете включить выборку трассировки (как описано в руководстве), а затем настроить выборку журнала на основе трассировки соответствующим образом:

builder.Logging.AddTraceBasedSampler();

Если выборка на основе трассировки включена, журналы будут создаваться только при выборке базового Activity образца. Решение выборки исходит из текущего Recorded значения.

Настройка случайной вероятностной выборки

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

  • Категория логов
  • Уровень логирования
  • Идентификатор события

Существует несколько способов настройки случайной вероятностной выборки с его правилами:

Конфигурация на основе файлов

Создайте раздел конфигурации в appsettings.json, например:

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug"
    }
  },

  "RandomProbabilisticSampler": {
    "Rules": [
      {
        "CategoryName": "Microsoft.AspNetCore.*",
        "Probability": 0.25,
        "LogLevel": "Information"
      },
      {
        "CategoryName": "System.*",
        "Probability": 0.1
      },
      {
        "EventId": 1001,
        "Probability": 0.05
      }
    ]
  }
}

Предыдущая конфигурация:

  • Примеры 10% журналов из категорий, начиная со System. всех уровней.
  • Примеры 25% логов из категорий, начиная с Microsoft.AspNetCore., LogLevel.Information.
  • Образцы 5% журналов с идентификатором события 1001, охватывающих все категории и уровни.
  • Отбирает 100% из всех других журналов.

Это важно

Значение Probability представляет вероятность со значениями от 0 до 1. Например, 0,25 означает, что будет отобрано 25% журналов. Значение 0 означает, что журналы не будут отбираться, а 1 означает, что все журналы будут отбираться. Эти значения 0 и 1 можно использовать для эффективного отключения или включения всех логов для конкретного правила. Вероятность не может быть меньше 0 или больше 1, и если это происходит в приложении, создается исключение.

Чтобы зарегистрировать самплер в конфигурации, воспользуйтесь следующим кодом:

builder.Logging.AddRandomProbabilisticSampler(builder.Configuration);

Изменение правил выборки в работающем приложении

Случайная вероятностная выборка поддерживает обновления конфигурации среды выполнения через IOptionsMonitor<TOptions> интерфейс. Если вы используете поставщик конфигурации, поддерживающий перезагрузку (например, поставщик конфигурации файлов), можно обновить правила выборки во время выполнения без перезапуска приложения.

Например, можно запустить приложение с помощью следующего appsettings.json, который эффективно выполняет роль no-op:

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 1
        }
      ]
    }
  }
}

Во время работы приложения можно обновить appsettings.json со следующей конфигурацией:

{
  "Logging": {
    "RandomProbabilisticSampler": {
      "Rules": [
        {
          "Probability": 0.01,
          "LogLevel": "Information"
        }
      ]
    }
  }
}

Новые правила будут применяться автоматически. Например, исходя из предыдущей конфигурации, выбирается 1% из журналов с LogLevel.Information.

Применение правил выборки

Алгоритм очень похож на фильтрацию журналов, но существуют некоторые различия.

Оценка правил выборки журналов выполняется для каждой записи журнала, однако существуют оптимизации производительности, например кэширование. Следующий алгоритм используется для каждой записи журнала для определенной категории:

  • Выберите правила с LogLevel равным или более высоким уровнем логов логгера.
  • Выберите правила, которые не идентифицированы или идентифицированы и равны идентификатору события журнала EventId.
  • Выберите правила с наибольшей длиной соответствующего префикса категории. Если совпадений не найдено, выберите все правила без категории.
  • Если выбрано несколько правил, примите последнее.
  • Если правила не выбраны, выборка не применяется, например, запись журнала передается как обычно.

Встроенная конфигурация кода

builder.Logging.AddRandomProbabilisticSampler(options =>
{
    options.Rules.Add(
        new RandomProbabilisticSamplerFilterRule(
            probability: 0.05d,
            eventId : 1001));
});

Предыдущая конфигурация:

  • Образцы 5% журналов с идентификатором события 1001, охватывающих все категории и уровни.
  • Отбирает 100% из всех других журналов.

Простая конфигурация вероятности

В базовых сценариях можно настроить одно значение вероятности, которое применяется ко всем журналам на указанном уровне или ниже указанного уровня:

builder.Logging.AddRandomProbabilisticSampler(0.01, LogLevel.Information);
builder.Logging.AddRandomProbabilisticSampler(0.1, LogLevel.Warning);

Приведенный выше код регистрирует сэмплер, который будет выбирать образцы из 10% Warning записей и 1% Information (и ниже) записей. Если в конфигурации не было правила для Information, было бы выбрано 10% Warning журналов и всех уровней ниже, включая Information.

Реализация настраиваемой выборки

Вы можете создать настраиваемую стратегию выборки, исходя из абстрактного LoggingSampler класса и переопределив ее абстрактные члены. Это позволяет настроить поведение выборки в соответствии с конкретными требованиями. Например, пользовательский семплер может:

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

Чтобы реализовать пользовательский самплер, выполните следующие действия.

  1. Создание класса, наследуемого от LoggingSampler.
  2. Переопределите метод LoggingSampler.ShouldSample для создания вашей пользовательской логики сбора данных.
  3. Зарегистрируйте пользовательский самплер в конвейере ведения журнала с помощью метода расширения AddSampler.

Для каждой записи журнала, которая не отфильтровывается, LoggingSampler.ShouldSample метод вызывается ровно один раз. Его возвращаемое значение определяет, следует ли выдавать запись журнала.

Вопросы, связанные с производительностью

Выборка журналов предназначена для снижения затрат на хранение с небольшим увеличением использования ЦП. Если приложение создает большой объем журналов, которые являются дорогостоящими для хранения, выборка может помочь уменьшить этот объем. При соответствующей настройке выборка может снизить затраты на хранение без потери информации, критической для диагностики инцидентов.

Встроенные выборки см. в разделе "Тесты".

Рекомендации по выбору уровня журнала и применению выборки

Уровень логирования Рекомендация
Trace Не применяйте выборку, так как обычно эти журналы отключены в рабочей среде
Debug Не применяйте выборку, так как обычно эти журналы отключены в рабочей среде
Information Применяйте выборку
Warning Рассмотрите возможность применения выборки
Error Не применяйте выборку
Critical Не применяйте выборку

Лучшие практики

  • Начните с более высоких частот выборки и настройте их вниз по мере необходимости.
  • Используйте правила на основе категорий для целевых компонентов.
  • Если вы используете распределенную трассировку, рассмотрите возможность реализации выборки на основе трассировки.
  • Совместно отслеживайте эффективность правил выборки.
  • Найдите правильный баланс для приложения— слишком низкая скорость выборки может снизить наблюдаемость, а слишком высокая скорость может увеличить затраты.

См. также