Ведение журналов в ASP.NET CoreLogging in ASP.NET Core

Авторы: Стив Смит (Steve Smith) и Том Дакстра (Tom Dykstra)By Steve Smith and Tom Dykstra

ASP.NET Core поддерживает API ведения журналов, который работает с разными встроенными и сторонними поставщиками.ASP.NET Core supports a logging API that works with a variety of built-in and third-party logging providers. В этой статье описано, как использовать в коде API ведения журналов, работающего со встроенными поставщиками.This article shows how to use the logging API with built-in providers.

Просмотреть или скачать образец кода (как скачивать)View or download sample code (how to download)

Добавление поставщиковAdd providers

Поставщик ведения журналов отображает или сохраняет журналы.A logging provider displays or stores logs. Например, поставщик Console отображает журналы на консоли, а поставщик Azure Application Insights может сохранить их в Azure Application Insights.For example, the Console provider displays logs on the console, and the Azure Application Insights provider stores them in Azure Application Insights. Журналы могут отправляться в несколько назначений после добавления нескольких поставщиков.Logs can be sent to multiple destinations by adding multiple providers.

Для добавления поставщика вызовите метод расширения Add{provider name} поставщика в файле Program.cs:To add a provider, call the provider's Add{provider name} extension method in Program.cs:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Шаблон проекта по умолчанию вызывает метод CreateDefaultBuilder, который добавляет следующие поставщики ведения журналов:The default project template calls CreateDefaultBuilder, which adds the following logging providers:

  • КонсольConsole
  • ОтладкаDebug
  • EventSource (начиная с версии ASP.NET Core 2.2)EventSource (starting in ASP.NET Core 2.2)
public static void Main(string[] args)
{
    CreateWebHostBuilder(args).Build().Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>();

Если вы используете CreateDefaultBuilder, поставщики по умолчанию можно заменить собственными поставщиками.If you use CreateDefaultBuilder, you can replace the default providers with your own choices. Вызовите ClearProviders и добавьте требуемые поставщики.Call ClearProviders, and add the providers you want.

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Чтобы использовать поставщик, установите его пакет NuGet и вызовите метод расширения поставщика в экземпляре ILoggerFactory.To use a provider, install its NuGet package and call the provider's extension method on an instance of ILoggerFactory:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole()
        .AddDebug();

Внедрение зависимостей (DI) ASP.NET Core предоставляет экземпляр ILoggerFactory.ASP.NET Core dependency injection (DI) provides the ILoggerFactory instance. Методы расширения AddConsole и AddDebug определены в пакетах Microsoft.Extensions.Logging.Console и Microsoft.Extensions.Logging.Debug.The AddConsole and AddDebug extension methods are defined in the Microsoft.Extensions.Logging.Console and Microsoft.Extensions.Logging.Debug packages. Каждый метод расширения вызывает метод ILoggerFactory.AddProvider, передавая экземпляр поставщика.Each extension method calls the ILoggerFactory.AddProvider method, passing in an instance of the provider.

Примечание

Пример приложения добавляет поставщиков ведения журнала в метод Startup.Configure.The sample app adds logging providers in the Startup.Configure method. Чтобы получить выходные данные журнала из выполняемого ранее кода, добавьте поставщики ведения журналов в конструктор класса Startup.To obtain log output from code that executes earlier, add logging providers in the Startup class constructor.

См. сведения о встроенных и сторонних поставщиках ведения журналов.Learn more about built-in logging providers and third-party logging providers later in the article.

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

Получите ILogger<TCategoryName> объект путем внедрения зависимостей.Get an ILogger<TCategoryName> object from DI.

В следующем примере контроллера создаются журналы Information и Warning.The following controller example creates Information and Warning logs. Категория — это TodoApiSample.Controllers.TodoController (полное имя класса TodoController в примере приложения):The category is TodoApiSample.Controllers.TodoController (the fully qualified class name of TodoController in the sample app):

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

В следующем примере Razor Pages создаются журналы с Information в качестве категории и TodoApiSample.Pages.AboutModel в качестве уровня:The following Razor Pages example creates logs with Information as the level and TodoApiSample.Pages.AboutModel as the category:

public class AboutModel : PageModel
{
    private readonly ILogger _logger;

    public AboutModel(ILogger<AboutModel> logger)
    {
        _logger = logger;
    }
public void OnGet()
{
    Message = $"About page visited at {DateTime.UtcNow.ToLongTimeString()}";
    _logger.LogInformation("Message displayed: {Message}", Message);
}
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

В предыдущем примере создаются журналы с Information и Warning в качестве уровня и классом TodoController в качестве категории.The preceding example creates logs with Information and Warning as the level and TodoController class as the category.

Уровень ведения журналов определяет степень серьезности или важности записанного в журнал события.The Log level indicates the severity of the logged event. Категория ведения журналов представляет строку, которая связана с каждым журналом.The log category is a string that is associated with each log. Экземпляр ILogger<T> создает журналы с полным именем типа T в качестве категории.The ILogger<T> instance creates logs that have the fully qualified name of type T as the category. Уровни и категории рассматриваются подробнее далее в этой статье.Levels and categories are explained in more detail later in this article.

Создание журналов в классе StartupCreate logs in Startup

Для записи журналов в классе Startup включите параметр ILogger в сигнатуру конструктора:To write logs in the Startup class, include an ILogger parameter in the constructor signature:

public class Startup
{
    private readonly ILogger _logger;

    public Startup(IConfiguration configuration, ILogger<Startup> logger)
    {
        Configuration = configuration;
        _logger = logger;
    }

    public IConfiguration Configuration { get; }

    public void ConfigureServices(IServiceCollection services)
    {
        services.AddMvc()
            .SetCompatibilityVersion(CompatibilityVersion.Version_2_2);

        // Add our repository type
        services.AddSingleton<ITodoRepository, TodoRepository>();
        _logger.LogInformation("Added TodoRepository to services");
    }

    public void Configure(IApplicationBuilder app, IHostingEnvironment env)
    {
        if (env.IsDevelopment())
        {
            _logger.LogInformation("In Development environment");
            app.UseDeveloperExceptionPage();
        }
        else
        {
            app.UseExceptionHandler("/Error");
            app.UseHsts();
        }

        app.UseHttpsRedirection();
        app.UseStaticFiles();
        app.UseCookiePolicy();

        app.UseMvc();
    }
}

Создание журналов в классе ProgramCreate logs in Program

Для записи журналов в классе Program получите экземпляр ILogger путем внедрения зависимостей:To write logs in the Program class, get an ILogger instance from DI:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .UseStartup<Startup>()
        .ConfigureLogging(logging =>
        {
            logging.ClearProviders();
            logging.AddConsole();
        });

Асинхронные методы ведения журналов не выполняютсяNo asynchronous logger methods

Скорость ведения журналов не должна влиять на производительность выполнения асинхронного кода.Logging should be so fast that it isn't worth the performance cost of asynchronous code. Если хранилище данных, предназначенное для регистрации сообщений журнала, работает медленно, сначала записывайте эти сообщения в быстродействующее хранилище,If your logging data store is slow, don't write to it directly. а затем перемещайте их в медленное хранилище.Consider writing the log messages to a fast store initially, then move them to the slow store later. Например, если вы входите в SQL Server, вам не нужно делать это непосредственно в методе Log, так как методы Log являются синхронными.For example, if you're logging to SQL Server, you don't want to do that directly in a Log method, since the Log methods are synchronous. Вместо этого синхронно добавьте сообщения журнала в очередь в памяти, и фоновый рабочий поток извлечет сообщения из очереди для выполнения асинхронных операций передачи данных в SQL Server.Instead, synchronously add log messages to an in-memory queue and have a background worker pull the messages out of the queue to do the asynchronous work of pushing data to SQL Server.

Параметр ConfigurationConfiguration

Конфигурацию поставщика ведения журналов предоставляет как минимум один поставщик конфигураций:Logging provider configuration is provided by one or more configuration providers:

  • Форматы файлов (INI, JSON и XML).File formats (INI, JSON, and XML).
  • аргументы командной строки.Command-line arguments.
  • Переменные среды.Environment variables.
  • Объекты .NET в памяти.In-memory .NET objects.
  • Незашифрованное хранилище Secret Manager (Диспетчер секретов).The unencrypted Secret Manager storage.
  • Зашифрованное пользовательское хранилище, например Azure Key Vault.An encrypted user store, such as Azure Key Vault.
  • Пользовательские поставщики (установленные или созданные).Custom providers (installed or created).

Например, конфигурацию ведения журналов обычно предоставляет раздел Logging в файле параметров приложения.For example, logging configuration is commonly provided by the Logging section of app settings files. В следующем примере показано содержимое типичного файла appsettings.Development.json.The following example shows the contents of a typical appsettings.Development.json file:

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

Свойство Logging может иметь свойство LogLevel и свойства поставщика журналов (здесь — Console).The Logging property can have LogLevel and log provider properties (Console is shown).

Свойство LogLevel в разделе Logging указывает минимальный уровень журнала для выбранных категорий.The LogLevel property under Logging specifies the minimum level to log for selected categories. В этом примере категории System и Microsoft записываются на уровне Information, а остальные — на уровне Debug.In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Другие свойства в разделе Logging определяют поставщиков ведения журналов.Other properties under Logging specify logging providers. Пример приведен для поставщика Console.The example is for the Console provider. Если поставщик поддерживает области журналов, IncludeScopes определяет, включены ли они.If a provider supports log scopes, IncludeScopes indicates whether they're enabled. Свойство поставщика (например, Console в этом примере) также определять свойство LogLevel.A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel под поставщиком указывает уровни журнала для этого поставщика.LogLevel under a provider specifies levels to log for that provider.

Если уровни указаны в Logging.{providername}.LogLevel, они не переопределяют ничего из того, что задано в Logging.LogLevel.If levels are specified in Logging.{providername}.LogLevel, they override anything set in Logging.LogLevel.

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

Ключи LogLevel представляют имена журналов.LogLevel keys represent log names. Ключ Default применяется к журналам, которые не указаны явно.The Default key applies to logs not explicitly listed. Значение представляет уровень ведения журнала, который применен к указанному журналу.The value represents the log level applied to the given log.

Сведения о реализации поставщиков конфигураций см. в статье Конфигурация в .NET Core.For information on implementing configuration providers, see Конфигурация в .NET Core.

Пример выходных данных ведения журналаSample logging output

В примере кода из предыдущего раздела журналы появляются в консоли после запуска приложения из командной строки.With the sample code shown in the preceding section, logs appear in the console when the app is run from the command line. Ниже приведен пример выходных данных консоли:Here's an example of console output:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:5000/api/todo/0
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 42.9286ms
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 148.889ms 404

Предыдущие журналы созданы путем отправки HTTP-запроса Get к примеру приложения по адресу http://localhost:5000/api/todo/0.The preceding logs were generated by making an HTTP Get request to the sample app at http://localhost:5000/api/todo/0.

Ниже приведен пример этих журналов в том виде, в каком они отображаются в окне отладки при запуске примера приложения в Visual Studio.Here's an example of the same logs as they appear in the Debug window when you run the sample app in Visual Studio:

Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request starting HTTP/1.1 GET http://localhost:53104/api/todo/0  
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
TodoApi.Controllers.TodoController:Information: Getting item 0
TodoApi.Controllers.TodoController:Warning: GetById(0) NOT FOUND
Microsoft.AspNetCore.Mvc.StatusCodeResult:Information: Executing HttpStatusCodeResult, setting HTTP status code 404
Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker:Information: Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 152.5657ms
Microsoft.AspNetCore.Hosting.Internal.WebHost:Information: Request finished in 316.3195ms 404

Журналы, которые созданы путем вызовов ILogger, как показано в предыдущем разделе, начинаются с TodoApi.Controllers.TodoController.The logs that are created by the ILogger calls shown in the preceding section begin with "TodoApi.Controllers.TodoController". Журналы, которые начинаются с категорий Microsoft, входят в код платформы ASP.NET Core.The logs that begin with "Microsoft" categories are from ASP.NET Core framework code. В ASP.NET Core и коде приложения используется один и тот же API ведения журналов и одни и те же поставщики.ASP.NET Core and application code are using the same logging API and providers.

В оставшейся части этой статьи рассматриваются некоторые сведения и параметры для ведения журналов.The remainder of this article explains some details and options for logging.

Пакеты NuGetNuGet packages

Интерфейсы ILogger и ILoggerFactory находятся в Microsoft.Extensions.Logging.Abstractions, а их реализации по умолчанию — в Microsoft.Extensions.Logging.The ILogger and ILoggerFactory interfaces are in Microsoft.Extensions.Logging.Abstractions, and default implementations for them are in Microsoft.Extensions.Logging.

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

При создании объекта ILogger для него указывается категория.When an ILogger object is created, a category is specified for it. Эта категория входит в состав каждого сообщения журнала, создаваемого этим экземпляром ILogger.That category is included with each log message created by that instance of ILogger. Категория может быть любой строкой, обычно используется имя класса, например TodoApi.Controllers.TodoController.The category may be any string, but the convention is to use the class name, such as "TodoApi.Controllers.TodoController".

Используйте ILogger<T> для получения экземпляра ILogger, который использует полное имя типа T в качестве категории:Use ILogger<T> to get an ILogger instance that uses the fully qualified type name of T as the category:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILogger<TodoController> logger)
    {
        _todoRepository = todoRepository;
        _logger = logger;
    }

Чтобы явно указать категорию, вызовите ILoggerFactory.CreateLogger:To explicitly specify the category, call ILoggerFactory.CreateLogger:

public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }
public class TodoController : Controller
{
    private readonly ITodoRepository _todoRepository;
    private readonly ILogger _logger;

    public TodoController(ITodoRepository todoRepository,
        ILoggerFactory logger)
    {
        _todoRepository = todoRepository;
        _logger = logger.CreateLogger("TodoApiSample.Controllers.TodoController");
    }

Использование ILogger<T> эквивалентно вызову CreateLogger с полным именем типа T.ILogger<T> is equivalent to calling CreateLogger with the fully qualified type name of T.

Уровень ведения журналаLog level

Каждый журнал задает значение LogLevel.Every log specifies a LogLevel value. Уровень ведения журналов означает степень серьезности или важности.The log level indicates the severity or importance. Например, можно создать журнал Information при нормальном завершении метода и журнал Warning, если метод возвращает код состояния 404 — не найдено.For example, you might write an Information log when a method ends normally and a Warning log when a method returns a 404 Not Found status code.

Следующий код создает журналы Informationи Warning:The following code creates Information and Warning logs:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

В коде выше первый параметр — это идентификатор события журнала.In the preceding code, the first parameter is the Log event ID. Второй параметр — это шаблон сообщения с заполнителями для значений аргументов, предоставляемых оставшимися параметрами метода.The second parameter is a message template with placeholders for argument values provided by the remaining method parameters. Параметры метода рассматриваются более подробно в разделе, посвященном шаблону сообщений далее в этой статье.The method parameters are explained in the message template section later in this article.

Методы журналов, которые содержат уровень в имени метода (например, LogInformation и LogWarning), являются методами расширения для ILogger.Log methods that include the level in the method name (for example, LogInformation and LogWarning) are extension methods for ILogger. Эти методы вызывают метод Log, принимающий параметр LogLevel.These methods call a Log method that takes a LogLevel parameter. Метод Log, в отличие от этих методов расширения, можно вызывать напрямую, однако его синтаксис довольно сложен.You can call the Log method directly rather than one of these extension methods, but the syntax is relatively complicated. См. сведения о ILogger и исходном коде расширений средства ведения журналов.For more information, see ILogger and the logger extensions source code.

В ASP.NET Core определяются следующие уровни ведения журналов, упорядоченные по возрастанию уровней серьезности.ASP.NET Core defines the following log levels, ordered here from lowest to highest severity.

  • Трассировка = 0Trace = 0

    Для получения сведений, которые полезны только при отладке.For information that's typically valuable only for debugging. Эти сообщения могут содержать конфиденциальные данные приложения, поэтому их не следует включать в рабочей среде.These messages may contain sensitive application data and so shouldn't be enabled in a production environment. По умолчанию отключено.Disabled by default.

  • Отладка = 1Debug = 1

    Для получения сведений, которые полезны при разработке и отладке.For information that may be useful in development and debugging. Пример Entering method Configure with flag set to true. Включайте уровни ведения журналов Debug в рабочей среде только при устранении неполадок, так как такие журналы занимают много места.Example: Entering method Configure with flag set to true. Enable Debug level logs in production only when troubleshooting, due to the high volume of logs.

  • Информация = 2Information = 2

    Для отслеживания общего потока работы приложения.For tracking the general flow of the app. Эти журналы обычно полезны в долгосрочной перспективе.These logs typically have some long-term value. Пример: Request received for path /api/todoExample: Request received for path /api/todo

  • Предупреждение = 3Warning = 3

    Для нестандартных или непредвиденных событий, возникающих в потоке работы приложения.For abnormal or unexpected events in the app flow. Это могут быть ошибки или другие условия, которые не приводят к остановке приложения, но которые нужно изучить.These may include errors or other conditions that don't cause the app to stop but might need to be investigated. Обработанные исключения являются распространенным условием использования уровня ведения журнала Warning.Handled exceptions are a common place to use the Warning log level. Пример: FileNotFoundException for file quotes.txt.Example: FileNotFoundException for file quotes.txt.

  • Ошибка = 4Error = 4

    Для ошибок и исключений, которые не могут быть обработаны.For errors and exceptions that cannot be handled. Эти сообщения указывают на сбой текущего действия или операции (например, текущего HTTP-запроса), а не на ошибку уровня приложения.These messages indicate a failure in the current activity or operation (such as the current HTTP request), not an app-wide failure. Пример сообщения журнала: Cannot insert record due to duplicate key violation.Example log message: Cannot insert record due to duplicate key violation.

  • Критический = 5Critical = 5

    Для сбоев, которые требуют немедленного внимания.For failures that require immediate attention. Примеры: потеря данных, нехватка места на диске.Examples: data loss scenarios, out of disk space.

Уровень ведения журналов можно использовать для управления объемом выходных данных, записываемых на определенный носитель или в окно отображения.Use the log level to control how much log output is written to a particular storage medium or display window. Например:For example:

  • В рабочей среде отправьте Trace в контексте уровня Information в хранилище томов.In production, send Trace through Information level to a volume data store. Отправьте Warning в контексте уровня Critical в хранилище томов.Send Warning through Critical to a value data store.
  • При разработке отправьте Warning в контексте Critical в консоль и добавьте Trace в контексте Information при устранении неполадок.During development, send Warning through Critical to the console, and add Trace through Information when troubleshooting.

В разделе Фильтрация журналов далее в этой статье приводятся сведения о том, как контролировать уровни журнала, обрабатываемые поставщиком.The Log filtering section later in this article explains how to control which log levels a provider handles.

ASP.NET Core создает журналы для событий платформы.ASP.NET Core writes logs for framework events. В примерах журнала ранее в этой статье не указывались журналы с уровнем ниже Information, поэтому журналы уровня Debug или Trace не создавались.The log examples earlier in this article excluded logs below Information level, so no Debug or Trace level logs were created. Ниже приведен пример журналов консоли, которые созданы при запуске примера приложения, настроенного на отображение журналов Debug:Here's an example of console logs produced by running the sample app configured to show Debug logs:

info: Microsoft.AspNetCore.Hosting.Internal.WebHost[1]
      Request starting HTTP/1.1 GET http://localhost:62555/api/todo/0
dbug: Microsoft.AspNetCore.Routing.Tree.TreeRouter[1]
      Request successfully matched the route with name 'GetTodo' and template 'api/Todo/{id}'.
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Update (TodoApi)' with id '089d59b6-92ec-472d-b552-cc613dfd625d' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ActionSelector[2]
      Action 'TodoApi.Controllers.TodoController.Delete (TodoApi)' with id 'f3476abe-4bd9-4ad3-9261-3ead09607366' did not match the constraint 'Microsoft.AspNetCore.Mvc.Internal.HttpMethodActionConstraint'
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action TodoApi.Controllers.TodoController.GetById (TodoApi)
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[1]
      Executing action method TodoApi.Controllers.TodoController.GetById (TodoApi) with arguments (0) - ModelState is Valid
info: TodoApi.Controllers.TodoController[1002]
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      GetById(0) NOT FOUND
dbug: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action method TodoApi.Controllers.TodoController.GetById (TodoApi), returned result Microsoft.AspNetCore.Mvc.NotFoundResult.
info: Microsoft.AspNetCore.Mvc.StatusCodeResult[1]
      Executing HttpStatusCodeResult, setting HTTP status code 404
info: Microsoft.AspNetCore.Mvc.Internal.ControllerActionInvoker[2]
      Executed action TodoApi.Controllers.TodoController.GetById (TodoApi) in 0.8788ms
dbug: Microsoft.AspNetCore.Server.Kestrel[9]
      Connection id "0HL6L7NEFF2QD" completed keep alive response.
info: Microsoft.AspNetCore.Hosting.Internal.WebHost[2]
      Request finished in 2.7286ms 404

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

Каждый журнал может указывать идентификатор события.Each log can specify an event ID. В примере приложения для этого используется локально определенный класс LoggingEvents:The sample app does this by using a locally defined LoggingEvents class:

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems = 1001;
    public const int GetItem = 1002;
    public const int InsertItem = 1003;
    public const int UpdateItem = 1004;
    public const int DeleteItem = 1005;

    public const int GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public class LoggingEvents
{
    public const int GenerateItems = 1000;
    public const int ListItems = 1001;
    public const int GetItem = 1002;
    public const int InsertItem = 1003;
    public const int UpdateItem = 1004;
    public const int DeleteItem = 1005;

    public const int GetItemNotFound = 4000;
    public const int UpdateItemNotFound = 4001;
}

Идентификатор события связывает набор событий.An event ID associates a set of events. Например, все журналы, связанные с отображением списка элементов на странице, могут иметь значение 1001.For example, all logs related to displaying a list of items on a page might be 1001.

Поставщик ведения журналов может хранить идентификатор события в поле идентификатора, в сообщении журнала, или вообще не хранить.The logging provider may store the event ID in an ID field, in the logging message, or not at all. Поставщик Debug не отображает идентификаторы событий.The Debug provider doesn't show event IDs. Поставщик Console отображает идентификаторы событий в квадратных скобках после категории:The console provider shows event IDs in brackets after the category:

info: TodoApi.Controllers.TodoController[1002]
      Getting item invalidid
warn: TodoApi.Controllers.TodoController[4000]
      GetById(invalidid) NOT FOUND

Шаблон сообщения журналаLog message template

Каждый журнал указывает шаблон сообщения.Each log specifies a message template. Шаблон сообщения может содержать заполнители, для которых предоставляются аргументы.The message template can contain placeholders for which arguments are provided. Используйте для заполнителей имена, а не числа.Use names for the placeholders, not numbers.

public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}
public IActionResult GetById(string id)
{
    _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
    var item = _todoRepository.Find(id);
    if (item == null)
    {
        _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
        return NotFound();
    }
    return new ObjectResult(item);
}

Параметры, используемые для предоставления значений, определяются порядком заполнителей, а не их именами.The order of placeholders, not their names, determines which parameters are used to provide their values. В приведенном ниже коде обратите внимание на то, что имена параметров идут не по порядку в шаблоне сообщения:In the following code, notice that the parameter names are out of sequence in the message template:

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

Этот код создает сообщение журнала со значениями параметров в определенном порядке:This code creates a log message with the parameter values in sequence:

Parameter values: parm1, parm2

Платформа ведения журналов поддерживает такое поведение, чтобы поставщики ведения журнала могли реализовывать семантическое ведение журналов, также известное как структурированное ведение журналов.The logging framework works this way so that logging providers can implement semantic logging, also known as structured logging. Сами аргументы передаются в систему ведения журналов, а не только в отформатированный шаблон сообщения.The arguments themselves are passed to the logging system, not just the formatted message template. Эта информация позволяет поставщикам ведения журналов хранить значения параметров как поля.This information enables logging providers to store the parameter values as fields. Предположим, например, что вызовы метода средства ведения журналов выглядят так:For example, suppose logger method calls look like this:

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

Если вы отправляете журналы в Хранилище таблиц Azure, каждая сущность таблицы Azure может иметь свойства ID и RequestTime, что упрощает выполнение запросов к данным журналов.If you're sending the logs to Azure Table Storage, each Azure Table entity can have ID and RequestTime properties, which simplifies queries on log data. Запрос может находить все журналы в пределах определенного диапазона RequestTime, не анализируя время ожидания текстового сообщения.A query can find all logs within a particular RequestTime range without parsing the time out of the text message.

Ведение журнала исключенийLogging exceptions

Методы средства ведения журнала имеют перегрузки, которые позволяют передавать исключение, как показано в следующем примере:The logger methods have overloads that let you pass in an exception, as in the following example:

catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);
catch (Exception ex)
{
    _logger.LogWarning(LoggingEvents.GetItemNotFound, ex, "GetById({ID}) NOT FOUND", id);
    return NotFound();
}
return new ObjectResult(item);

Разные поставщики обрабатывают сведения об исключениях по-разному.Different providers handle the exception information in different ways. Ниже приведен пример выходных данных поставщика Debug из приведенного выше кода.Here's an example of Debug provider output from the code shown above.

TodoApi.Controllers.TodoController:Warning: GetById(036dd898-fb01-47e8-9a65-f92eb73cf924) NOT FOUND

System.Exception: Item not found exception.
 at TodoApi.Controllers.TodoController.GetById(String id) in C:\logging\sample\src\TodoApi\Controllers\TodoController.cs:line 226

Фильтрация журналовLog filtering

Можно указать минимальный уровень ведения журнала для определенного поставщика и категории или для всех поставщиков или всех категорий.You can specify a minimum log level for a specific provider and category or for all providers or all categories. Все журналы с уровнем ниже минимального не передаются этому поставщику, поэтому они не отображаются и не сохраняются.Any logs below the minimum level aren't passed to that provider, so they don't get displayed or stored.

Чтобы проигнорировать все журналы, укажите LogLevel.None в качестве минимального уровня ведения журналов.To suppress all logs, specify LogLevel.None as the minimum log level. LogLevel.None равно целочисленному значению 6, то есть больше, чем LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Создание правил фильтрации в конфигурацииCreate filter rules in configuration

Код шаблона проектов вызывает CreateDefaultBuilder для настройки ведения журналов для поставщиков Console и Debug.The project template code calls CreateDefaultBuilder to set up logging for the Console and Debug providers. Метод CreateDefaultBuilder также настраивает ведение журнала для просмотра конфигурации в разделе Logging, используя код, аналогичный следующему:The CreateDefaultBuilder method also sets up logging to look for configuration in a Logging section, using code like the following:

public static void Main(string[] args)
{
    var webHost = new WebHostBuilder()
        .UseKestrel()
        .UseContentRoot(Directory.GetCurrentDirectory())
        .ConfigureAppConfiguration((hostingContext, config) =>
        {
            var env = hostingContext.HostingEnvironment;
            config.AddJsonFile("appsettings.json", optional: true, reloadOnChange: true)
                  .AddJsonFile($"appsettings.{env.EnvironmentName}.json", 
                      optional: true, reloadOnChange: true);
            config.AddEnvironmentVariables();
        })
        .ConfigureLogging((hostingContext, logging) =>
        {
            logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
            logging.AddConsole();
            logging.AddDebug();
            logging.AddEventSourceLogger();
        })
        .UseStartup<Startup>()
        .Build();

    webHost.Run();
}

Данные конфигурации указывают минимальные уровни ведения журнала для каждого поставщика и категории, как показано в следующем примере:The configuration data specifies minimum log levels by provider and category, as in the following example:

{
  "Logging": {
    "Debug": {
      "LogLevel": {
        "Default": "Information"
      }
    },
    "Console": {
      "IncludeScopes": false,
      "LogLevel": {
        "Microsoft.AspNetCore.Mvc.Razor.Internal": "Warning",
        "Microsoft.AspNetCore.Mvc.Razor.Razor": "Debug",
        "Microsoft.AspNetCore.Mvc.Razor": "Error",
        "Default": "Information"
      }
    },
    "LogLevel": {
      "Default": "Debug"
    }
  }
}

Этот JSON создает шесть правил фильтрации: одно для поставщика Debug, четыре для поставщика Console и одно для всех поставщиков.This JSON creates six filter rules: one for the Debug provider, four for the Console provider, and one for all providers. При создании объекта ILogger для каждого поставщика выбирается только одно из этих правил.A single rule is chosen for each provider when an ILogger object is created.

Правила фильтрации в кодеFilter rules in code

В следующем примере показано, как зарегистрировать в коде правила фильтрации:The following example shows how to register filter rules in code:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging =>
        logging.AddFilter("System", LogLevel.Debug)
               .AddFilter<DebugLoggerProvider>("Microsoft", LogLevel.Trace));

Второй AddFilter указывает поставщика, Debug, используя имя его типа.The second AddFilter specifies the Debug provider by using its type name. Первый AddFilter применяется ко всем поставщикам, так как он не определяет тип поставщика.The first AddFilter applies to all providers because it doesn't specify a provider type.

Применение правил фильтрацииHow filtering rules are applied

Данные конфигурации и код AddFilter, приведенный в предыдущих примерах, создают правила, показанные в следующей таблице.The configuration data and the AddFilter code shown in the preceding examples create the rules shown in the following table. Первые шесть взяты из примера конфигурации, а последние два — из примера кода.The first six come from the configuration example and the last two come from the code example.

ЧислоNumber ПоставщикProvider Категории, которые начинаются с...Categories that begin with ... Минимальный уровень ведения журналаMinimum log level
11 ОтладкаDebug Все категорииAll categories СведенияInformation
22 КонсольConsole Microsoft.AspNetCore.Mvc.Razor.InternalMicrosoft.AspNetCore.Mvc.Razor.Internal ПредупреждениеWarning
33 КонсольConsole Microsoft.AspNetCore.Mvc.Razor.RazorMicrosoft.AspNetCore.Mvc.Razor.Razor ОтладкаDebug
44 КонсольConsole Microsoft.AspNetCore.Mvc.RazorMicrosoft.AspNetCore.Mvc.Razor ErrorError
55 КонсольConsole Все категорииAll categories СведенияInformation
66 Все поставщикиAll providers Все категорииAll categories ОтладкаDebug
77 Все поставщикиAll providers СистемаSystem ОтладкаDebug
88 ОтладкаDebug МайкрософтMicrosoft ТрассировкаTrace

При создании объекта ILogger объект ILoggerFactory выбирает одно правило для каждого поставщика, которое будет применено к этому средству ведения журналов.When an ILogger object is created, the ILoggerFactory object selects a single rule per provider to apply to that logger. Все сообщения, записываемые с помощью экземпляра ILogger, фильтруются на основе выбранных правил.All messages written by an ILogger instance are filtered based on the selected rules. Самое подходящее правило для каждой пары поставщика и категории выбирается из списка доступных правил.The most specific rule possible for each provider and category pair is selected from the available rules.

При создании ILogger для данной категории для каждого поставщика используется приведенный далее алгоритм:The following algorithm is used for each provider when an ILogger is created for a given category:

  • Выберите все правила, которые соответствуют поставщику или его псевдониму.Select all rules that match the provider or its alias. Если ничего не найдено, выберите все правила с пустым поставщиком.If no match is found, select all rules with an empty provider.
  • В результатах предыдущего шага выберите правила с самым длинным соответствующим префиксом категории.From the result of the preceding step, select rules with longest matching category prefix. Если ничего не найдено, выберите все правила, которые не указывают категорию.If no match is found, select all rules that don't specify a category.
  • Если выбрано несколько правил, примите последнее.If multiple rules are selected, take the last one.
  • Если правила не выбраны, используйте MinimumLevel.If no rules are selected, use MinimumLevel.

Предположим, у вас есть указанный выше список правил и вы создаете объект ILogger для категории Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine:With the preceding list of rules, suppose you create an ILogger object for category "Microsoft.AspNetCore.Mvc.Razor.RazorViewEngine":

  • К поставщику Debug применяются правила 1, 6 и 8.For the Debug provider, rules 1, 6, and 8 apply. Правило 8 является наиболее подходящим, поэтому выбрано оно.Rule 8 is most specific, so that's the one selected.
  • К поставщику отладки применяются правила 3, 4, 5 и 6.For the Console provider, rules 3, 4, 5, and 6 apply. Правило 3 является наиболее подходящим.Rule 3 is most specific.

Полученный в результате экземпляр ILogger отправляет журналы уровня Trace и выше в поставщик Debug.The resulting ILogger instance sends logs of Trace level and above to the Debug provider. Журналы уровня Debug и выше отправляются в поставщик Console.Logs of Debug level and above are sent to the Console provider.

Псевдонимы поставщиковProvider aliases

Каждый поставщик определяет псевдоним, используемый в конфигурации вместо полного имени типа.Each provider defines an alias that can be used in configuration in place of the fully qualified type name. Для встроенных поставщиков используйте следующие псевдонимы:For the built-in providers, use the following aliases:

  • КонсольConsole
  • ОтладкаDebug
  • EventSourceEventSource
  • EventLogEventLog
  • TraceSourceTraceSource
  • AzureAppServicesFileAzureAppServicesFile
  • AzureAppServicesBlobAzureAppServicesBlob
  • ApplicationInsightsApplicationInsights

Минимальный уровень по умолчаниюDefault minimum level

Существует параметр минимального уровня, который применяется, только если к определенному поставщику или категории не подходят правила из конфигурации или кода.There's a minimum level setting that takes effect only if no rules from configuration or code apply for a given provider and category. В следующем примере показано, как задать минимальный уровень:The following example shows how to set the minimum level:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logging => logging.SetMinimumLevel(LogLevel.Warning));

Если минимальный уровень не задан явным образом, используется значение по умолчанию — Information, означающее, что журналы Trace и Debug игнорируются.If you don't explicitly set the minimum level, the default value is Information, which means that Trace and Debug logs are ignored.

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

Функция фильтрации вызывается для всех поставщиков и категорий, которым в конфигурации и (или) коде не назначены правила.A filter function is invoked for all providers and categories that don't have rules assigned to them by configuration or code. Код в функции имеет доступ к типу поставщика, категории и уровню ведения журналов.Code in the function has access to the provider type, category, and log level. Например:For example:

WebHost.CreateDefaultBuilder(args)
    .UseStartup<Startup>()
    .ConfigureLogging(logBuilder =>
    {
        logBuilder.AddFilter((provider, category, logLevel) =>
        {
            if (provider == "Microsoft.Extensions.Logging.Console.ConsoleLoggerProvider" &&
                category == "TodoApiSample.Controllers.TodoController")
            {
                return false;
            }
            return true;
        });
    });

Некоторые поставщики ведения журналов позволяют указывать, когда журналы следует записывать на носитель, а когда — игнорировать. При этом учитывается уровень ведения журнала и категория.Some logging providers let you specify when logs should be written to a storage medium or ignored based on log level and category.

Методы расширения AddConsole и AddDebugпредоставляют перегрузки для принятия условий фильтрации.The AddConsole and AddDebug extension methods provide overloads that accept filtering criteria. В следующем примере кода поставщик Console игнорирует журналы с уровнем ниже Warning, а поставщик Debug не учитывает журналы, создаваемые платформой.The following sample code causes the console provider to ignore logs below Warning level, while the Debug provider ignores logs that the framework creates.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(LogLevel.Warning)
        .AddDebug((category, logLevel) => (category.Contains("TodoApi") && logLevel >= LogLevel.Trace));

Метод AddEventLog имеет перегрузку, принимающую экземпляр EventLogSettings, который в своем свойстве Filter может содержать функцию фильтрации.The AddEventLog method has an overload that takes an EventLogSettings instance, which may contain a filtering function in its Filter property. Поставщик TraceSource не предоставляет эти перегрузки, так как уровень ведения журнала и другие параметры определяются для него на основе используемых SourceSwitch и TraceListener.The TraceSource provider doesn't provide any of those overloads, since its logging level and other parameters are based on the SourceSwitch and TraceListener it uses.

Чтобы задать правила фильтрации для всех поставщиков, которые зарегистрированы в экземпляре ILoggerFactory, используйте метод расширения WithFilter.To set filtering rules for all providers that are registered with an ILoggerFactory instance, use the WithFilter extension method. В приведенном ниже примере журналы платформы (категория начинается с Microsoft или System) ограничиваются предупреждениями. При этом разрешается ведение журналов на уровне отладки для журналов, созданных кодом приложения.The example below limits framework logs (category begins with "Microsoft" or "System") to warnings while logging at debug level for logs created by application code.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .WithFilter(new FilterLoggerSettings
        {
            { "Microsoft", LogLevel.Warning },
            { "System", LogLevel.Warning },
            { "ToDoApi", LogLevel.Debug }
        })
        .AddConsole()
        .AddDebug();

Чтобы запретить запись журналов, укажите LogLevel.None как минимальный уровень ведения журналов.To prevent any logs from being written, specify LogLevel.None as the minimum log level. LogLevel.None равно целочисленному значению 6, то есть больше, чем LogLevel.Critical (5).The integer value of LogLevel.None is 6, which is higher than LogLevel.Critical (5).

Пакет NuGet Microsoft.Extensions.Logging.Filter предоставляет метод расширения WithFilter.The WithFilter extension method is provided by the Microsoft.Extensions.Logging.Filter NuGet package. Метод возвращает новый экземпляр ILoggerFactory для фильтрации журнала сообщений, переданного всем поставщикам средства ведения журналов, которые зарегистрированы в этом экземпляре.The method returns a new ILoggerFactory instance that will filter the log messages passed to all logger providers registered with it. Он не влияет на другие экземпляры ILoggerFactory, включая исходный экземпляр ILoggerFactory.It doesn't affect any other ILoggerFactory instances, including the original ILoggerFactory instance.

Системные категории и уровниSystem categories and levels

Ниже приведены некоторые категории, используемые ASP.NET Core и Entity Framework Core с заметками о журналах:Here are some categories used by ASP.NET Core and Entity Framework Core, with notes about what logs to expect from them:

КатегорияCategory ПримечанияNotes
Microsoft.AspNetCoreMicrosoft.AspNetCore Общая диагностика ASP.NET Core.General ASP.NET Core diagnostics.
Microsoft.AspNetCore.DataProtectionMicrosoft.AspNetCore.DataProtection Распознанные, найденные и использованные ключи.Which keys were considered, found, and used.
Microsoft.AspNetCore.HostFilteringMicrosoft.AspNetCore.HostFiltering Разрешенные узлы.Hosts allowed.
Microsoft.AspNetCore.HostingMicrosoft.AspNetCore.Hosting Время начала и длительность выполнения HTTP-запросов.How long HTTP requests took to complete and what time they started. Определение загруженных начальных сборок размещения.Which hosting startup assemblies were loaded.
Microsoft.AspNetCore.MvcMicrosoft.AspNetCore.Mvc Диагностика MVC и Razor.MVC and Razor diagnostics. Привязка моделей, выполнение фильтра, компиляция представлений, выбор действия.Model binding, filter execution, view compilation, action selection.
Microsoft.AspNetCore.RoutingMicrosoft.AspNetCore.Routing Перенаправление соответствующих сведений.Route matching information.
Microsoft.AspNetCore.ServerMicrosoft.AspNetCore.Server Запуск, остановка и сохранение ответов.Connection start, stop, and keep alive responses. Сведения о сертификате HTTPS.HTTPS certificate information.
Microsoft.AspNetCore.StaticFilesMicrosoft.AspNetCore.StaticFiles Обработанные файлы.Files served.
Microsoft.EntityFrameworkCoreMicrosoft.EntityFrameworkCore Общая диагностика Entity Framework Core.General Entity Framework Core diagnostics. Действия и конфигурация базы данных, обнаружение изменений, переносы.Database activity and configuration, change detection, migrations.

Области журналовLog scopes

Область может группировать набор логических операций.A scope can group a set of logical operations. Эту возможность можно использовать для присоединения одних и тех же данных к каждому журналу, созданному как часть набора.This grouping can be used to attach the same data to each log that's created as part of a set. Например, каждый журнал, созданный в ходе обработки транзакции, может включать идентификатор транзакции.For example, every log created as part of processing a transaction can include the transaction ID.

Область — это тип IDisposable, возвращаемый методом BeginScope и действующий до удаления.A scope is an IDisposable type that's returned by the BeginScope method and lasts until it's disposed. Используйте область, заключив вызовы средства ведения журналов в блок using:Use a scope by wrapping logger calls in a using block:

public IActionResult GetById(string id)
{
    TodoItem item;
    using (_logger.BeginScope("Message attached to logs created in the using block"))
    {
        _logger.LogInformation(LoggingEvents.GetItem, "Getting item {ID}", id);
        item = _todoRepository.Find(id);
        if (item == null)
        {
            _logger.LogWarning(LoggingEvents.GetItemNotFound, "GetById({ID}) NOT FOUND", id);
            return NotFound();
        }
    }
    return new ObjectResult(item);
}

Следующий код предоставляет области для поставщика Console:The following code enables scopes for the console provider:

Program.cs:Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Примечание

Для включения ведения журнала на уровне области требуется параметр IncludeScopes средства ведения журналов.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Сведения о настройках см. в разделе Конфигурация.For information on configuration, see the Configuration section.

Program.cs:Program.cs:

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));
    logging.AddConsole(options => options.IncludeScopes = true);
    logging.AddDebug();
})

Примечание

Для включения ведения журнала на уровне области требуется параметр IncludeScopes средства ведения журналов.Configuring the IncludeScopes console logger option is required to enable scope-based logging.

Startup.cs:Startup.cs:

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddConsole(includeScopes: true)
        .AddDebug();

Каждое сообщение журнала содержит ограниченную информацию:Each log message includes the scoped information:

info: TodoApi.Controllers.TodoController[1002]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      Getting item 0
warn: TodoApi.Controllers.TodoController[4000]
      => RequestId:0HKV9C49II9CK RequestPath:/api/todo/0 => TodoApi.Controllers.TodoController.GetById (TodoApi) => Message attached to logs created in the using block
      GetById(0) NOT FOUND

Встроенные поставщики ведения журналовBuilt-in logging providers

В состав ASP.NET Core входят следующие поставщики:ASP.NET Core ships the following providers:

См. сведения о Устранение неполадок ASP.NET Core в службах IISведении журналов stdoutУстранение неполадок ASP.NET Core в службе приложений Azure.For information about stdout logging, see Устранение неполадок ASP.NET Core в службах IIS and Устранение неполадок ASP.NET Core в службе приложений Azure.

Поставщик ConsoleConsole provider

Пакет поставщика Microsoft.Extensions.Logging.Console отправляет выходные данные журнала на консоль.The Microsoft.Extensions.Logging.Console provider package sends log output to the console.

logging.AddConsole();
loggerFactory.AddConsole();

Перегрузки AddConsole позволяют передавать минимальный уровень ведения журналов, функцию фильтрации и логическое значение, определяющее поддержку областей.AddConsole overloads let you pass in a minimum log level, a filter function, and a boolean that indicates whether scopes are supported. Другим вариантом является передача объекта IConfiguration, который может указать поддержку областей и уровни ведения журнала.Another option is to pass in an IConfiguration object, which can specify scopes support and logging levels.

Поставщик Console оказывает значительное влияние на производительность и потому, как правило, не подходит для использования в рабочей среде.The console provider has a significant impact on performance and is generally not appropriate for use in production.

При создании проекта в Visual Studio метод AddConsole выглядит следующим образом:When you create a new project in Visual Studio, the AddConsole method looks like this:

loggerFactory.AddConsole(Configuration.GetSection("Logging"));

Этот код ссылается на раздел Logging файла appSettings.json:This code refers to the Logging section of the appSettings.json file:

{
  "Logging": {
    "Console": {
      "IncludeScopes": false
    },
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    }
  }
}

Приведенные параметры ограничивают журналы платформы предупреждениями, но разрешают регистрацию приложений на уровне отладки, как описано в разделе Фильтрация журналов.The settings shown limit framework logs to warnings while allowing the app to log at debug level, as explained in the Log filtering section. Дополнительные сведения см. в разделе Конфигурация.For more information, see Configuration.

Чтобы просмотреть выходные данные ведения журналов в консоли, откройте командную строку, перейдите в папку проекта и запустите приведенную ниже команду:To see console logging output, open a command prompt in the project folder and run the following command:

dotnet run

Поставщик DebugDebug provider

Пакет поставщика Microsoft.Extensions.Logging.Debug записывает выходные данные журналов с помощью класса System.Diagnostics.Debug (вызовов метода Debug.WriteLine).The Microsoft.Extensions.Logging.Debug provider package writes log output by using the System.Diagnostics.Debug class (Debug.WriteLine method calls).

В Linux этот поставщик записывает журналы в каталог /var/log/message.On Linux, this provider writes logs to /var/log/message.

logging.AddDebug();
loggerFactory.AddDebug();

Перегрузки AddDebug позволяют передавать минимальный уровень ведения журнала или функцию фильтрации.AddDebug overloads let you pass in a minimum log level or a filter function.

Поставщик EventSourceEventSource provider

Для приложений, предназначенных для ASP.NET Core 1.1.0 или более поздней версии, реализовывать события трассировки можно с помощью пакета поставщика Microsoft.Extensions.Logging.EventSource.For apps that target ASP.NET Core 1.1.0 or later, the Microsoft.Extensions.Logging.EventSource provider package can implement event tracing. В Windows используется трассировка событий Windows.On Windows, it uses ETW. Поставщик является кроссплатформенным, но для Linux и macOS инструменты сбора событий и отображений пока отсутствуют.The provider is cross-platform, but there are no event collection and display tools yet for Linux or macOS.

logging.AddEventSourceLogger();
loggerFactory.AddEventSourceLogger();

Для сбора и просмотра данных журналов рекомендуется использовать программу PerfView.A good way to collect and view logs is to use the PerfView utility. Существуют и другие средства для просмотра журналов трассировки событий Windows, но PerfView обеспечивает максимальное удобство работы с событиями трассировки событий Windows, создаваемыми ASP.NET.There are other tools for viewing ETW logs, but PerfView provides the best experience for working with the ETW events emitted by ASP.NET.

Чтобы настроить PerfView для сбора событий, регистрируемых этим поставщиком, добавьте строку *Microsoft-Extensions-Logging в список Дополнительные поставщики.To configure PerfView for collecting events logged by this provider, add the string *Microsoft-Extensions-Logging to the Additional Providers list. (Не пропустите звездочку в начале строки.)(Don't miss the asterisk at the start of the string.)

Дополнительные поставщики Perfview

Поставщик Windows EventLogWindows EventLog provider

Пакет поставщика Microsoft.Extensions.Logging.EventLog отправляет выходные данные журнала в журнал событий Windows.The Microsoft.Extensions.Logging.EventLog provider package sends log output to the Windows Event Log.

logging.AddEventLog();
loggerFactory.AddEventLog();

Перегрузки AddEventLog позволяют передавать EventLogSettings или минимальный уровень ведения журнала.AddEventLog overloads let you pass in EventLogSettings or a minimum log level.

Поставщик TraceSourceTraceSource provider

Пакет поставщика Microsoft.Extensions.Logging.TraceSource использует библиотеки и поставщики TraceSource.The Microsoft.Extensions.Logging.TraceSource provider package uses the TraceSource libraries and providers.

logging.AddTraceSource(sourceSwitchName);
loggerFactory.AddTraceSource(sourceSwitchName);

Перегрузки AddTraceSource позволяют передавать исходный параметр и прослушиватель трассировки.AddTraceSource overloads let you pass in a source switch and a trace listener.

Чтобы использовать этот поставщик, приложение должно выполняться в .NET Framework (а не в .NET Core).To use this provider, an app has to run on the .NET Framework (rather than .NET Core). Поставщик позволяет перенаправлять сообщения различным прослушивателям, например TextWriterTraceListener, который используется в примере приложения.The provider can route messages to a variety of listeners, such as the TextWriterTraceListener used in the sample app.

В следующем примере показана настройка поставщика TraceSource, записывающего в окне консоли сообщения типа Warning и сообщения с более высоким уровнем серьезности.The following example configures a TraceSource provider that logs Warning and higher messages to the console window.

public void Configure(IApplicationBuilder app,
    IHostingEnvironment env,
    ILoggerFactory loggerFactory)
{
    loggerFactory
        .AddDebug();

    // add Trace Source logging
    var testSwitch = new SourceSwitch("sourceSwitch", "Logging Sample");
    testSwitch.Level = SourceLevels.Warning;
    loggerFactory.AddTraceSource(testSwitch,
        new TextWriterTraceListener(writer: Console.Out));

Поставщик службы приложений AzureAzure App Service provider

Пакет поставщика Microsoft.Extensions.Logging.AzureAppServices записывает журналы в текстовые файлы в файловой системе приложения службы приложений Azure и в хранилище больших двоичных объектов в учетной записи хранения Azure.The Microsoft.Extensions.Logging.AzureAppServices provider package writes logs to text files in an Azure App Service app's file system and to blob storage in an Azure Storage account. Пакет поставщика доступен для приложений, предназначенных для .NET Core 1.1 или более поздней версии.The provider package is available for apps targeting .NET Core 1.1 or later.

Если планируется использовать .NET Core, обратите внимание на следующее.If targeting .NET Core, note the following points:

Если планируется использовать .NET Framework или будет указана ссылка на метапакет Microsoft.AspNetCore.App, добавьте пакет поставщика в проект.If targeting .NET Framework or referencing the Microsoft.AspNetCore.App metapackage, add the provider package to the project. Вызовите AddAzureWebAppDiagnostics:Invoke AddAzureWebAppDiagnostics:

logging.AddAzureWebAppDiagnostics();
loggerFactory.AddAzureWebAppDiagnostics();

Перегрузка AddAzureWebAppDiagnostics позволяет передавать AzureAppServicesDiagnosticsSettings.An AddAzureWebAppDiagnostics overload lets you pass in AzureAppServicesDiagnosticsSettings. Объект параметров может переопределять параметры по умолчанию, например шаблон выходных данных ведения журналов, имя BLOB-объекта и максимально допустимый размер файла.The settings object can override default settings, such as the logging output template, blob name, and file size limit. (Шаблон выходных данных — это шаблон сообщений, который применяется ко всем журналам наряду с тем, что предоставляется при вызове метода ILogger.)(Output template is a message template that's applied to all logs in addition to what's provided with an ILogger method call.)

Для настройки параметров поставщика используйте AzureFileLoggerOptions и AzureBlobLoggerOptions, как показано в следующем примере:To configure provider settings, use AzureFileLoggerOptions and AzureBlobLoggerOptions, as shown in the following example:

public static void Main(string[] args)
{
    var host = CreateWebHostBuilder(args).Build();

    var todoRepository = host.Services.GetRequiredService<ITodoRepository>();
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Feed the dog" });
    todoRepository.Add(new Core.Model.TodoItem() { Name = "Walk the dog" });

    var logger = host.Services.GetRequiredService<ILogger<Program>>();
    logger.LogInformation("Seeded the database.");

    host.Run();
}

public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
    WebHost.CreateDefaultBuilder(args)
        .ConfigureLogging(logging => logging.AddAzureWebAppDiagnostics())
        .ConfigureServices(serviceCollection => serviceCollection
                .Configure<AzureFileLoggerOptions>(options =>
                {
                    options.FileName = "azure-diagnostics-";
                    options.FileSizeLimit = 50 * 1024;
                    options.RetainedFileCountLimit = 5;
                }).Configure<AzureBlobLoggerOptions>(options =>
                {
                    options.BlobName = "log.txt";
                }))
        .UseStartup<Startup>();

При развертывании в приложение службы приложений ваше приложение учитывает параметры в разделе Журналы диагностики на странице Служба приложений на портале Azure.When you deploy to an App Service app, the application honors the settings in the Diagnostic Logs section of the App Service page of the Azure portal. При обновлении этих параметров изменения вступают в силу немедленно без перезапуска или повторного развертывания приложения.When these settings are updated, the changes take effect immediately without requiring a restart or redeployment of the app.

Параметры ведения журнала Azure

По умолчанию файлы журнала находятся в папке D:\home\LogFiles\Application, а имя файла по умолчанию — diagnostics-yyyymmdd.txt.The default location for log files is in the D:\home\LogFiles\Application folder, and the default file name is diagnostics-yyyymmdd.txt. Максимальный размер файла по умолчанию составляет 10 МБ, а максимальное количество сохраняемых по умолчанию файлов равно 2.The default file size limit is 10 MB, and the default maximum number of files retained is 2. Имя BLOB-объекта по умолчанию — {имя_приложения}{метка_времени}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.The default blob name is {app-name}{timestamp}/yyyy/mm/dd/hh/{guid}-applicationLog.txt.

Поставщик работает только при выполнении проекта в среде Azure.The provider only works when the project runs in the Azure environment. Он не функционирует при запуске проекта в локальной среде —(то есть не выполняет запись в локальные файлы или в локальное хранилище разработки для больших двоичных объектов).It has no effect when the project is run locally—it doesn't write to local files or local development storage for blobs.

Потоковая передача журналов AzureAzure log streaming

Потоковая передача журналов Azure позволяет просматривать активность журнала в реальном времени из следующих источников:Azure log streaming lets you view log activity in real time from:

  • сервер приложений;The app server
  • веб-сервер;The web server
  • трассировка неудачно завершенных запросов.Failed request tracing

Настройка потоковой передачи журналов AzureTo configure Azure log streaming:

  • Со страницы портала приложения перейдите на страницу Журналы диагностики.Navigate to the Diagnostics Logs page from your app's portal page.
  • Включите параметр Ведение журнала приложения (файловая система).Set Application Logging (Filesystem) to On.

Страница журналов диагностики на портале Azure

Перейдите на страницу Потоковая передача журналов, чтобы просмотреть сообщения приложения.Navigate to the Log Streaming page to view app messages. Они записываются в журнал приложением через интерфейс ILogger.They're logged by the app through the ILogger interface.

Потоковая передача журнала приложения на портале Azure

Ведение журнала трассировки Azure Application InsightsAzure Application Insights trace logging

Пакет поставщика Microsoft.Extensions.Logging.ApplicationInsights записывает журналы в Azure Application Insights.The Microsoft.Extensions.Logging.ApplicationInsights provider package writes logs to Azure Application Insights. Служба Application Insights отслеживает веб-приложения и предоставляет средства для создания запросов и анализа данных телеметрии.Application Insights is a service that monitors a web app and provides tools for querying and analyzing the telemetry data. Используя этого поставщика, вы сможете выполнять запросы к журналам и их анализ с помощью средств Application Insights.If you use this provider, you can query and analyze your logs by using the Application Insights tools.

Поставщик ведения журнала включается как зависимость Microsoft.ApplicationInsights.AspNetCore. Этот пакет предоставляет всю доступную телеметрию для ASP.NET Core.The logging provider is included as a dependency of Microsoft.ApplicationInsights.AspNetCore, which is the package that provides all available telemetry for ASP.NET Core. Если вы используете этот пакет, пакет поставщика устанавливать не нужно.If you use this package, you don't have to install the provider package.

Не используйте пакет Microsoft.ApplicationInsights.Web, который предназначен для ASP.NET 4.x.Don't use the Microsoft.ApplicationInsights.Web package—that's for ASP.NET 4.x.

Дополнительные сведения см. в следующих ресурсах:For more information, see the following resources:

Примечание

По состоянию на 1 мая 2019 года статья Application Insights для приложений ASP.NET Core является устаревшей, и инструкции из этого руководства не работают.As of 5/1/2019, the article titled Application Insights for ASP.NET Core is out of date, and the tutorial steps don't work. Используйте вместо нее эту статью.Refer to Application Insights for ASP.NET Core applications instead. Мы знаем об этой проблеме и работаем над ее устранением.We are aware of the issue and are working to correct it.

Сторонние поставщики ведения журналовThird-party logging providers

Некоторые сторонние платформы ведения журналов, которые работают с ASP.NET Core:Third-party logging frameworks that work with ASP.NET Core:

Некоторые сторонние платформы выполняют семантическое ведение журналов, также известное как структурированное ведение журналов.Some third-party frameworks can perform semantic logging, also known as structured logging.

Использование сторонней платформы аналогично использованию одного из встроенных поставщиков:Using a third-party framework is similar to using one of the built-in providers:

  1. Добавьте пакет NuGet в проект.Add a NuGet package to your project.
  2. Вызовите ILoggerFactory.Call an ILoggerFactory.

Дополнительные сведения см. в документации по каждому поставщику.For more information, see each provider's documentation. Сторонние поставщики ведения журналов не поддерживаются корпорацией Майкрософт.Third-party logging providers aren't supported by Microsoft.

Дополнительные ресурсыAdditional resources