Выборка журнала в .NET

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

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

Замечание

Одновременно можно использовать только один сэмплер. При регистрации нескольких семплеров используется последний.

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

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

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

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

Интерфейс командной строки .NET
СсылкаНаПакет

dotnet add package Microsoft.Extensions.Telemetry

<ItemGroup>
  <PackageReference Include="Microsoft.Extensions.Telemetry"
                    Version="*" />
</ItemGroup>

Дополнительные сведения см. в разделе 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, который эффективно действует в качестве пустой операции.

{
  "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 класса и переопределив ее абстрактные члены. Это позволяет настроить поведение выборки в соответствии с конкретными требованиями. Например, пользовательский семплер может:

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

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

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

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

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

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

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

Руководство по уровню логирования при использовании выборки

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

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

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

См. также

Обратная связь

Были ли сведения на этой странице полезными?

Last updated on 2026-02-05