Логирование в C# и .NET

.NET поддерживает высокую производительность, структурированное ведение журнала через ILogger API для мониторинга поведения приложений и диагностики проблем. Настройте разных поставщиков ведения журналов для записи журналов в разные места назначения. Основные поставщики журналирования встроены, и доступны многие сторонние поставщики.

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

В первом примере показаны основные сведения, но он подходит только для тривиального консольного приложения. В этом примере консольного приложения используются следующие пакеты NuGet:

• Microsoft.Extensions.Logging
• Microsoft.Extensions.Logging.Console

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

using Microsoft.Extensions.Logging;

using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");

Предшествующий пример:

• Создает объект ILoggerFactory. ILoggerFactory хранит всю конфигурацию, определяющую, куда отправляются сообщения журнала. В этом случае настройте поставщик ведения журнала консоли таким образом, чтобы сообщения журнала записываются в консоль.
• Создает категорию ILogger с именем Program. Категория — это string, связанная с каждым сообщением, зарегистрированным объектом ILogger. Он группирует сообщения журнала из одного класса (или категории) вместе при поиске или фильтрации журналов.
• Вызывает LogInformation для регистрации сообщения на уровне Information. Уровень журнала указывает серьезность зарегистрированного события и отфильтровывает менее важные сообщения журнала. Запись журнала также включает шаблон сообщения"Hello World! Logging is {Description}." и пару Description = fun "ключ-значение". Имя ключа (или заполнитель) берется из слова внутри фигурных скобок в шаблоне, а значение исходит от другого аргумента метода.

Этот файл проекта для этого примера включает два пакета NuGet:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net8.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.10" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.10" />
  </ItemGroup>

</Project>

Ведение журнала в нетривиальном приложении

Рассмотрите возможность внесения этих изменений в предыдущий пример при входе в менее тривиальный сценарий:

• Если ваше приложение использует внедрение зависимостей (DI) или хост, например WebApplication ASP.NET или Generic Host, используйте ILoggerFactory и ILogger объекты из соответствующих контейнеров DI вместо создания их напрямую. Дополнительные сведения см. в разделе «Интеграция с DI и hosts».

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

using Microsoft.Extensions.Logging;

internal partial class Program
{
    static void Main(string[] args)
    {
        using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
        ILogger logger = factory.CreateLogger("Program");
        LogStartupMessage(logger, "fun");
    }

    [LoggerMessage(Level = LogLevel.Information, Message = "Hello World! Logging is {Description}.")]
    static partial void LogStartupMessage(ILogger logger, string description);
}

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

using Microsoft.Extensions.Logging;

internal class Program
{
    static void Main(string[] args)
    {
        using ILoggerFactory factory = LoggerFactory.Create(builder => builder.AddConsole());
        ILogger logger = factory.CreateLogger<Program>();
        logger.LogInformation("Hello World! Logging is {Description}.", "fun");
    }
}

• Если вы не используете журналы консоли в качестве единственного рабочего решения для мониторинга, добавьте поставщиков журналов, которые вы планируете использовать. Например, используйте OpenTelemetry для отправки журналов по протоколу OTLP (протокол OpenTelemetry):

using Microsoft.Extensions.Logging;
using OpenTelemetry.Logs;

using ILoggerFactory factory = LoggerFactory.Create(builder =>
{
    builder.AddOpenTelemetry(logging =>
    {
        logging.AddOtlpExporter();
    });
});
ILogger logger = factory.CreateLogger("Program");
logger.LogInformation("Hello World! Logging is {Description}.", "fun");

Интеграция с узлами и внедрением зависимостей

Если приложение использует внедрение зависимостей (DI) или узел, например WebApplication или Generic Host от ASP.NET, используйте ILoggerFactory и ILogger объекты из контейнера DI, а не создавать их напрямую.

Получите ILogger из DI

В этом примере получается объект ILogger в размещенном приложении с помощью ASP.NET Minimal APIs:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton<ExampleHandler>();

var app = builder.Build();

var handler = app.Services.GetRequiredService<ExampleHandler>();
app.MapGet("/", handler.HandleRequest);

app.Run();

partial class ExampleHandler(ILogger<ExampleHandler> logger)
{
    public string HandleRequest()
    {
        LogHandleRequest(logger);
        return "Hello World";
    }

    [LoggerMessage(LogLevel.Information, "ExampleHandler.HandleRequest was called")]
    public static partial void LogHandleRequest(ILogger logger);
}

Предшествующий пример:

• Создана одноэлементная служба ExampleHandler, которая сопоставляет входящие веб-запросы для запуска функции ExampleHandler.HandleRequest.
• Строка 12 задает основной конструктор для ExampleHandler, добавленный в C# 12. Использование более старого конструктора C# работает одинаково хорошо, но немного более подробно.
• Конструктор определяет параметр типа ILogger<ExampleHandler>. ILogger<TCategoryName> является производным от ILogger и указывает, какая категория ILogger имеет объект. Контейнер DI находит элемент ILogger с правильной категорией и предоставляет его в качестве аргумента конструктора. Если ILogger с этой категорией еще не существует, контейнер DI автоматически создает его из ILoggerFactory поставщика услуг.
• Параметр logger, полученный в конструкторе, используется для логирования в функции HandleRequest.

ILoggerFactory, предоставленный сервером

Построитель узлов инициализирует конфигурацию по умолчанию, а затем добавляет настроенный ILoggerFactory объект в контейнер DI узла при создании узла. Перед сборкой хоста настройте конфигурацию ведения журнала с помощью HostApplicationBuilder.Logging, WebApplicationBuilder.Logging или аналогичных API для других хостов. Хосты также применяют конфигурацию ведения журнала из источников конфигурации по умолчанию, таких как appsettings.json и переменные среды. Дополнительные сведения см. в статье Конфигурация в .NET.

Этот пример расширяет предыдущий, чтобы настроить ILoggerFactory, предоставленный WebApplicationBuilder. Он добавляет OpenTelemetry в качестве поставщика ведения журнала, передавающего журналы по протоколу OTLP (протокол OpenTelemetry):

var builder = WebApplication.CreateBuilder(args);
builder.Logging.AddOpenTelemetry(logging => logging.AddOtlpExporter());
builder.Services.AddSingleton<ExampleHandler>();
var app = builder.Build();

Создание ILoggerFactory с помощью DI

Если вы используете контейнер DI без узла, используйте AddLogging для настройки и добавления ILoggerFactory в контейнер.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;

// Add services to the container including logging
var services = new ServiceCollection();
services.AddLogging(builder => builder.AddConsole());
services.AddSingleton<ExampleService>();
IServiceProvider serviceProvider = services.BuildServiceProvider();

// Get the ExampleService object from the container
ExampleService service = serviceProvider.GetRequiredService<ExampleService>();

// Do some pretend work
service.DoSomeWork(10, 20);

class ExampleService(ILogger<ExampleService> logger)
{
    public void DoSomeWork(int x, int y)
    {
        logger.LogInformation("DoSomeWork was called. x={X}, y={Y}", x, y);
    }
}

Предшествующий пример:

• Создан контейнер службы DI, содержащий ILoggerFactory, настроенный для записи в консоль
• Добавлен синглтон ExampleService в контейнер
• Создал экземпляр ExampleService контейнера DI, который также автоматически создал объект ILogger<ExampleService> для использования в качестве аргумента конструктора.
• Вызван ExampleService.DoSomeWork, который использовал ILogger<ExampleService> для записи сообщения в консоль.

Настроить ведение журнала

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

Настройка ведения журнала без кода

Для приложений, использующих хост, "Logging" раздел appsettings.{Environment}.json файлов обычно предоставляет конфигурацию логирования. Для приложений, которые не используют хост, явно настройте внешние источники конфигурации или настройте их в коде.

Шаблоны рабочей службы .NET создают следующий файл appsettings.Development.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft": "Warning",
      "Microsoft.Hosting.Lifetime": "Information"
    }
  }
}

В предыдущем объекте JSON:

• Указаны категории уровней журнала "Default", "Microsoft" и "Microsoft.Hosting.Lifetime".
• Значение "Default" применяется ко всем категориям, которые не указаны в противном случае, эффективно делая все значения по умолчанию для всех категорий "Information". Переопределите это поведение, указав значение для категории.
• Категория "Microsoft" применяется ко всем категориям, начинающимся с "Microsoft".
• Записи категории "Microsoft" регистрируются на уровне журнала Warning и выше.
• Категория "Microsoft.Hosting.Lifetime" более конкретна, чем категория "Microsoft", поэтому категория "Microsoft.Hosting.Lifetime" ведёт логирование на уровне "Information" и выше.
• Конкретный поставщик журналов не указан, поэтому LogLevel применяется ко всем включенным поставщикам ведения журналов, кроме журнала событий Windows.

Свойство Logging может включать как свойства LogLevel, так и свойства поставщика журналов. Свойство LogLevel указывает минимальный уровень для записи в журнал для выбранных категорий. В приведенном выше коде JSON заданы уровни ведения журнала Information и Warning. LogLevel определяет уровень серьезности записей журнала и варьируется в диапазоне от 0 до 6:

Trace = 0, Debug = 1, Information = 2, Warning = 3, Error = 4, Critical = 5 и None = 6.

Если задан LogLevel, логирование будет вестись для сообщений с указанного уровня и выше. В предыдущем JSON ведется журнал для категории Default и более высоких уровней Information. Например, в журнал записываются сообщения Information, Warning, Error и Critical. Если LogLevel не задан, по умолчанию устанавливается уровень журналирования Information. Дополнительную информацию см. в разделе Уровни журналов.

Свойство поставщика может указывать свойство LogLevel. Свойство LogLevel указывает уровни ведения журналов для этого поставщика и переопределяет общие параметры ведения журналов, не связанные с поставщиком. Рассмотрите следующий файл appsettings.json:

{
    "Logging": {
        "LogLevel": {
            "Default": "Error",
            "Microsoft": "Warning"
        },
        "Debug": {
            "LogLevel": {
                "Default": "Information",
                "Microsoft.Hosting": "Trace"
            }
        },
        "EventSource": {
            "LogLevel": {
                "Default": "Warning"
            }
        }
    }
}

Параметры в Logging.{ProviderName}.LogLevel переопределяют параметры в Logging.LogLevel. В приведенном выше JSON для поставщика Debug установлен уровень ведения журнала по умолчанию Information.

Logging:Debug:LogLevel:Default:Information

Приведенный выше параметр задает уровень ведения журнала Information для всех категорий Logging:Debug:, за исключением Microsoft.Hosting. Если задана конкретная категория, она переопределяет категорию по умолчанию. В приведенном выше коде JSON категории Logging:Debug:LogLevel"Microsoft.Hosting" и "Default" переопределяют параметры в Logging:LogLevel.

Укажите минимальный уровень журнала для любого из следующих вариантов:

• Определенные поставщики: например Logging:EventSource:LogLevel:Default:Information
• Конкретные категории: например, Logging:LogLevel:Microsoft:Warning
• Все поставщики и все категории: Logging:LogLevel:Default:Warning

Журналы, которые находятся ниже минимального уровня, не учитываются:

• переданы поставщику
• регистрируются или отображаются.

Чтобы отключить все журналы, укажите LogLevel.None. LogLevel.None имеет значение 6, то есть выше LogLevel.Critical (5).

Если поставщик поддерживает области журналов, IncludeScopes указывает, включены ли они. Дополнительные сведения см. в разделе области журналов .

Следующий файл appsettings.json содержит параметры для всех встроенных поставщиков:

{
    "Logging": {
        "LogLevel": {
            "Default": "Error",
            "Microsoft": "Warning",
            "Microsoft.Hosting.Lifetime": "Warning"
        },
        "Debug": {
            "LogLevel": {
                "Default": "Information"
            }
        },
        "Console": {
            "IncludeScopes": true,
            "LogLevel": {
                "Microsoft.Extensions.Hosting": "Warning",
                "Default": "Information"
            }
        },
        "EventSource": {
            "LogLevel": {
                "Microsoft": "Information"
            }
        },
        "EventLog": {
            "LogLevel": {
                "Microsoft": "Information"
            }
        },
        "AzureAppServicesFile": {
            "IncludeScopes": true,
            "LogLevel": {
                "Default": "Warning"
            }
        },
        "AzureAppServicesBlob": {
            "IncludeScopes": true,
            "LogLevel": {
                "Microsoft": "Information"
            }
        },
        "ApplicationInsights": {
            "LogLevel": {
                "Default": "Information"
            }
        }
    }
}

В предыдущем примере:

• Категории и уровни не являются предлагаемыми значениями. В примере показаны все поставщики по умолчанию.
• Параметры в Logging.{ProviderName}.LogLevel переопределяют параметры в Logging.LogLevel. Например, уровень в Debug.LogLevel.Default переопределяет уровень в LogLevel.Default.
• Для каждого поставщика используется псевдоним. Каждый поставщик определяет псевдоним , который можно использовать в конфигурации вместо полного имени типа. Псевдонимы встроенных поставщиков:
  • Console
  • Debug
  • EventSource
  • EventLog
  • AzureAppServicesFile
  • AzureAppServicesBlob
  • ApplicationInsights

Настройка уровня ведения журнала с помощью командной строки, переменных среды и других способов конфигурации

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

:: Assigns the env var to the value
setx "Logging__LogLevel__Microsoft" "Information" /M

:: Prints the env var value
echo %Logging__LogLevel__Microsoft%

# Assigns the env var to the value
[System.Environment]::SetEnvironmentVariable(
    "Logging__LogLevel__Microsoft", "Information", "Machine")

# Prints the env var value
[System.Environment]::GetEnvironmentVariable(
    "Logging__LogLevel__Microsoft", "Machine")

# Assigns the env var to the value, persists it across sessions
echo export Logging__LogLevel__Microsoft="Information" >> ~/.bashrc && source ~/.bashrc

# Prints the env var value
echo $Logging__LogLevel__Microsoft

# Or use printenv:
# printenv Logging__LogLevel__Microsoft

Предыдущий параметр среды сохраняется в среде. Чтобы проверить параметры при работе с приложением, созданным на базе шаблонов рабочей службы .NET, выполните команду dotnet run в каталоге проекта после назначения переменной среды.

dotnet run

В Службе приложений Azure выберите Новый параметр приложения на странице Параметры > Конфигурация. Параметры приложения Службы приложений Azure:

• Шифруются, когда они неактивны, и передаются по зашифрованному каналу.
• Предоставляются в качестве переменных среды.

Дополнительные сведения о настройке значений конфигурации .NET с помощью переменных среды см. в разделе переменные среды.

Настройка ведения журнала с помощью кода

Чтобы настроить логирование в коде, используйте API ILoggingBuilder. Доступ к нему можно получить из разных мест:

• Создавая ILoggerFactory напрямую, настройте его в LoggerFactory.Create.
• При использовании DI без узла, настройте в LoggingServiceCollectionExtensions.AddLogging.
• При использовании узла настраивайте с помощью HostApplicationBuilder.Logging, WebApplicationBuilder.Logging или других API, специфичных для узла.

В этом примере показано задание поставщика ведения журнала для консоли и нескольких фильтров.

using Microsoft.Extensions.Logging;

using var loggerFactory = LoggerFactory.Create(static builder =>
{
    builder
        .AddFilter("Microsoft", LogLevel.Warning)
        .AddFilter("System", LogLevel.Warning)
        .AddFilter("LoggingConsoleApp.Program", LogLevel.Debug)
        .AddConsole();
});

ILogger logger = loggerFactory.CreateLogger<Program>();
logger.LogDebug("Hello {Target}", "Everyone");

В предыдущем примере AddFilterнастраивается уровень логирования, установленный для различных категорий. AddConsole добавляет консольный провайдер ведения журнала. По умолчанию журналы с Debug серьезностью не включены, но так как конфигурация изменяет фильтры, на консоли отображается отладочное сообщение "Hello Everyone".

Применение правил фильтрации

При создании объекта ILogger<TCategoryName> объект ILoggerFactory выбирает одно правило для каждого поставщика, которое будет применено к этому средству ведения журналов. Экземпляр ILogger фильтрует все сообщения, записываемые им на основе выбранных правил. Самое подробное правило для каждой пары поставщика и категории выбирается из списка доступных правил.

При создании ILogger для данной категории для каждого поставщика используется приведенный далее алгоритм:

• Выберите все правила, которые соответствуют поставщику или его псевдониму. Если соответствие не найдено, выберите все правила с пустым поставщиком.
• В результатах предыдущего шага выберите правила с самым длинным соответствующим префиксом категории. Если совпадений не найдено, выберите все правила без категории.
• Если выбрано несколько правил, примите последнее.
• Если правила не выбраны, укажите минимальный уровень ведения журнала с помощью LoggingBuilderExtensions.SetMinimumLevel(ILoggingBuilder, LogLevel).

Категория журналирования

При создании объекта ILogger указывается категория. Эта категория включена в каждое сообщение журнала, созданное этим экземпляром ILogger. Строка категории является произвольной, но соглашение заключается в том, чтобы использовать полное имя класса. Например, категория может называться "Example.DefaultService", если служба в приложении определяется как следующий объект:

namespace Example
{
    public class DefaultService : IService
    {
        private readonly ILogger<DefaultService> _logger;

        public DefaultService(ILogger<DefaultService> logger) =>
            _logger = logger;

        // ...
    }
}

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

namespace Example
{
    public class DefaultService : IService
    {
        private readonly ILogger _logger;

        public DefaultService(ILoggerFactory loggerFactory) =>
            _logger = loggerFactory.CreateLogger("Example.DefaultService.CustomCategory");

        // ...
    }
}

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

Использование ILogger<T> эквивалентно вызову CreateLogger с полностью квалифицированным именем типа T.

Уровень логирования

В следующей таблице перечислены значения LogLevel, используемый для удобства метод расширения Log{LogLevel}, а также приводятся сведения о предполагаемом применении:

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

Первый параметр метода Log, LogLevel, указывает на степень серьезности лога. Вместо вызова Log(LogLevel, ...) большинство разработчиков вызывают методы расширения Log{LogLevel}. Метод расширения Log{LogLevel} вызывает метод Log и указывает LogLevel. Например, следующие два вызова ведения журнала функционально эквивалентны и позволяют получить одинаковые журналы:

public void LogDetails()
{
    var logMessage = "Details for log.";

    _logger.Log(LogLevel.Information, AppLogEvents.Details, logMessage);
    _logger.LogInformation(AppLogEvents.Details, logMessage);
}

AppLogEvents.Details содержит идентификатор события и неявным образом представляется постоянным значением Int32. AppLogEvents обозначает класс, который предоставляет разные именованные константы для идентификаторов и отображается в разделе Идентификатор события журнала.

Следующий код создает журналы Informationи Warning:

public async Task<T> GetAsync<T>(string id)
{
    _logger.LogInformation(AppLogEvents.Read, "Reading value for {Id}", id);

    var result = await _repository.GetAsync(id);
    if (result is null)
    {
        _logger.LogWarning(AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
    }

    return result;
}

В приведенном выше коде первый Log{LogLevel} параметр AppLogEvents.Read— это идентификатор события журнала. Второй параметр — это шаблон сообщения с заполнителями для значений аргументов, предоставляемых оставшимися параметрами метода. Параметры метода рассматриваются более подробно в разделе, посвященном шаблону сообщений далее в этой статье.

Настройте подходящий уровень ведения журнала и вызовите правильные методы Log{LogLevel}, чтобы управлять объемом данных журнала, записываемых на определенный носитель. Например:

• В производстве
  • При ведении журнала на уровнях Trace или Debug создается большой объем подробных сообщений журнала. Чтобы контролировать затраты и не превышать лимиты объема хранилища данных, записывайте сообщения уровня Trace и Debug в хранилище данных с большим объемом и низкими затратами. Рассмотрите возможность ограничения уровней Trace и Debug конкретными категориями.
  • При ведении журналов от Warning до Critical должно создаваться мало сообщений.
    • При этом стоимость и ограничения хранения, как правило, не важны.
    • Меньший объем журналов позволяет выбирать среди большего количества вариантов хранения данных.
• В разработке:
  • Задайте значение Warning.
  • Добавляйте сообщения Trace или Debug при устранении неполадок. Чтобы ограничить объем выходных данных, задавайте уровни Trace или Debug только для исследуемых категорий.

Приведенный ниже код JSON задает Logging:Console:LogLevel:Microsoft:Information.

{
    "Logging": {
        "LogLevel": {
            "Microsoft": "Warning"
        },
        "Console": {
            "LogLevel": {
                "Microsoft": "Information"
            }
        }
    }
}

Идентификатор события в журнале

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

using Microsoft.Extensions.Logging;

internal static class AppLogEvents
{
    internal static EventId Create = new(1000, "Created");
    internal static EventId Read = new(1001, "Read");
    internal static EventId Update = new(1002, "Updated");
    internal static EventId Delete = new(1003, "Deleted");

    // These are also valid EventId instances, as there's
    // an implicit conversion from int to an EventId
    internal const int Details = 3000;
    internal const int Error = 3001;

    internal static EventId ReadNotFound = 4000;
    internal static EventId UpdateNotFound = 4001;

    // ...
}

Идентификатор события связывает набор событий. Например, все журналы, связанные с чтением значений из репозитория, могут иметь идентификатор 1001.

Поставщик ведения журнала может записывать идентификатор события в поле идентификатора, в сообщении ведения журнала или вообще нет. Поставщик Debug не отображает идентификаторы событий. Поставщик Console отображает идентификаторы событий в квадратных скобках после категории:

info: Example.DefaultService.GetAsync[1001]
      Reading value for a1b2c3
warn: Example.DefaultService.GetAsync[4000]
      GetAsync(a1b2c3) not found

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

Шаблон сообщения журнала логов

Каждый API ведения журнала использует шаблон сообщения. Шаблон сообщения может содержать заполнители, для которых предоставляются аргументы. Используйте для заполнителей имена, а не числа. Параметры, используемые для предоставления значений, определяются порядком заполнителей, а не их именами. В приведенном ниже коде имена параметров идут не по порядку в шаблоне сообщения:

string p1 = "param1";
string p2 = "param2";
_logger.LogInformation("Parameter values: {p2}, {p1}", p1, p2);

Приведенный выше код создает сообщение журнала со значениями параметров в определенном порядке:

Parameter values: param1, param2

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

_logger.LogInformation("Getting item {Id} at {RunTime}", id, DateTime.Now);

Например, при ведении журнала в хранилище таблиц Azure:

• каждая сущность таблицы Azure может иметь свойства ID и RunTime;
• использование таблиц со свойствами позволяет упростить выполнение запросов к данным журнала. Например, с помощью запроса можно находить все журналы в пределах определенного диапазона RunTime, не анализируя время ожидания текстового сообщения.

Форматирование шаблона сообщения журнала

Шаблоны сообщений журнала поддерживают форматирование переменных заполнителей. Шаблоны могут указывать любой допустимый формат для заданного аргумента типа. Рассмотрим следующий Information шаблон сообщения журнала:

_logger.LogInformation("Logged on {PlaceHolderName:MMMM dd, yyyy}", DateTimeOffset.UtcNow);
// Logged on January 06, 2022

В предыдущем примере экземпляр DateTimeOffset является типом, соответствующим PlaceHolderName в шаблоне сообщения журнала. Это название может быть любым, так как оно основано на порядковых значениях. Формат MMMM dd, yyyy является допустимым для типа DateTimeOffset.

Для получения дополнительной информации о форматировании DateTime и DateTimeOffset см. Пользовательские строки формата даты и времени.

Примеры

В данных примерах показано, как отформатировать шаблон сообщения, используя синтаксис заполнителя {}. Кроме того, показан пример экранирования синтаксиса заполнителя {} с его выходными данными. Наконец, интерполяция строк с заполнителями шаблонов также показана:

logger.LogInformation("Number: {Number}", 1);               // Number: 1
logger.LogInformation("{{Number}}: {Number}", 3);           // {Number}: 3
logger.LogInformation($"{{{{Number}}}}: {{Number}}", 5);    // {Number}: 5

Запись исключений в журнал

Методы логгера имеют перегрузки, принимающие параметр исключения.

public void Test(string id)
{
    try
    {
        if (id is "none")
        {
            throw new Exception("Default Id detected.");
        }
    }
    catch (Exception ex)
    {
        _logger.LogWarning(
            AppLogEvents.Error, ex,
            "Failed to process iteration: {Id}", id);
    }
}

Принципы записи исключений в журнал зависят от конкретного поставщика.

Уровень ведения журнала по умолчанию

Если уровень журнала по умолчанию не задан, значение уровня журнала по умолчанию равно Information.

Давайте рассмотрим следующее приложение службы рабочих процессов:

• Создано на основе шаблонов .NET Worker.
• файлы appsettings.json и appsettings.Development.json были удалены или переименованы.

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

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

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.SetMinimumLevel(LogLevel.Warning);

using IHost host = builder.Build();

await host.RunAsync();

Функция фильтрации

Функция фильтрации вызывается для всех поставщиков и категорий, которым в конфигурации и (или) коде не назначены правила:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.AddFilter((provider, category, logLevel) =>
{
    return provider.Contains("ConsoleLoggerProvider")
        && (category.Contains("Example") || category.Contains("Microsoft"))
        && logLevel >= LogLevel.Information;
});

using IHost host = builder.Build();

await host.RunAsync();

Приведенный выше код отображает журналы консоли, если категория содержит Example или Microsoft и задан уровень ведения журнала Information или выше.

Области логирования

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

Область:

• имеет тип IDisposable, который возвращается методом BeginScope;
• Действует до момента его удаления.

Области поддерживаются следующими поставщиками:

• Console
• AzureAppServicesFile и AzureAppServicesBlob
• ApplicationInsightsLoggerProvider

Используйте область действия, заключив вызовы средства ведения журналов в блок using.

public async Task<T> GetAsync<T>(string id)
{
    T result;
    var transactionId = Guid.NewGuid().ToString();

    using (_logger.BeginScope(new List<KeyValuePair<string, object>>
        {
            new KeyValuePair<string, object>("TransactionId", transactionId),
        }))
    {
        _logger.LogInformation(
            AppLogEvents.Read, "Reading value for {Id}", id);

        var result = await _repository.GetAsync(id);
        if (result is null)
        {
            _logger.LogWarning(
                AppLogEvents.ReadNotFound, "GetAsync({Id}) not found", id);
        }
    }

    return result;
}

Следующий JSON предоставляет области действия для поставщика console:

{
    "Logging": {
        "Debug": {
            "LogLevel": {
                "Default": "Information"
            }
        },
        "Console": {
            "IncludeScopes": true,
            "LogLevel": {
                "Microsoft": "Warning",
                "Default": "Information"
            }
        },
        "LogLevel": {
            "Default": "Debug"
        }
    }
}

Следующий код предоставляет области для поставщика Console:

HostApplicationBuilder builder = Host.CreateApplicationBuilder(args);

builder.Logging.ClearProviders();
builder.Logging.AddSimpleConsole(options => options.IncludeScopes = true);

using IHost host = builder.Build();

await host.RunAsync();

Создание журналов в Main

Следующий код выполняет вход в Main, получая экземпляр ILogger из DI после инициализации хоста.

using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;

using IHost host = Host.CreateApplicationBuilder(args).Build();

var logger = host.Services.GetRequiredService<ILogger<Program>>();
logger.LogInformation("Host created.");

await host.RunAsync();

Предыдущий код основан на двух пакетах NuGet:

• Microsoft.Extensions.Hosting
• Microsoft.Extensions.Logging

Его файл проекта выглядит примерно так:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>net7.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Hosting" Version="7.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging" Version="7.0.0" />
  </ItemGroup>

</Project>

Отсутствуют асинхронные методы ведения журнала

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

Изменение уровней ведения журнала в работающем приложении

API ведения журнала не включает сценарий для изменения уровней журнала во время работы приложения. Однако некоторые поставщики конфигурации могут перезагрузить конфигурацию, которая немедленно влияет на конфигурацию ведения журнала. Например, поставщик конфигурации файлов по умолчанию перезагружает конфигурацию ведения журнала. При изменении конфигурации в коде во время выполнения приложения приложение может вызвать IConfigurationRoot.Reload , чтобы обновить конфигурацию ведения журнала приложения.

Пакеты NuGet

Интерфейсы ILogger<TCategoryName> и их реализации ILoggerFactory включены в большинство SDK для .NET в качестве неявной ссылки на пакет. Они также явно доступны в следующих пакетах NuGet, если они не ссылаются неявно.

• Эти интерфейсы находятся в пространстве имен Microsoft.Extensions.Logging.Abstractions.
• Их реализации по умолчанию находятся в пакете Microsoft.Extensions.Logging.

Для получения дополнительной информации о том, какой SDK для .NET включает неявные ссылки на пакеты, см. раздел SDK для .NET: таблица неявных пространств имен.

См. также

• Поставщики логирования в .NET
• Реализация пользовательского поставщика ведения журнала в .NET
• Форматирование журнала консоли
• Логирование с высокой производительностью в .NET
• Руководство по ведению журнала для авторов библиотек .NET
• Ошибки журналирования должны быть созданы в репозитории github.com/dotnet/runtime