Make a doc for the LoggerMessage.DefineScope pattern

[BrennanConroy]

We should document the low allocation logging pattern that uses LoggerMessage.DefineScope and LoggerMessage.Define as seen here https://github.com/aspnet/KestrelHttpServer/blob/b41c4078bdbbf2b2413fe13922a64552ed1177b6/src/Microsoft.AspNetCore.Server.Kestrel/Internal/Infrastructure/KestrelTrace.cs and https://github.com/aspnet/Mvc/blob/624909763bf762c4448955d00eef1649737df8d6/src/Microsoft.AspNetCore.Mvc.Razor/Internal/MvcRazorLoggerExtensions.cs

[glennc]

I think some guidance around the implications of mixing something like string interpolation and formatters will be useful to add as well.

[guardrex]

@Rick-Anderson

• Would you like this as a sub-topic to fundamentals/logging.md in the TOC?
• Title? 🏎️ High-performance logging with LoggerMessage in ASP.NET Core 🏎️

[Rick-Anderson]

@guardrex sounds good. cc @scottaddie

[guardrex]

@Rick-Anderson @scottaddie Proposal for this topic ...

Title: High-performance logging with LoggerMessage in ASP.NET Core
TOC: sub-topic to fundamentals/logging.md

Outline

• Introduction
  • LoggerMessage feature description (1-2 sentences)
  • Sample link
• Describe LoggerMessage.Define and LoggerMessage.DefineScope
• Illustrate LoggerMessage.Define using the sample
• Illustrate LoggerMessage.DefineScope using the sample

[Rick-Anderson]

@BrennanConroy @glennc can you review the outline? LGTM.

[BrennanConroy]

👍

[guardrex]

@glennc @BrennanConroy

TL;DR

This ...

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConsole(options => options.IncludeScopes = true);
})

... is absolutely required to make scopes work? If so, then why is the IncludeScopes setting in the templates?

Rubber duck

Need a head-check on scopes config behavior:

1. I have IncludeScopes set to true in appsettings files.
2. I see that the logging config is handled by WebHost's CreateDefaultBuilder: https://github.com/aspnet/MetaPackages/blob/dev/src/Microsoft.AspNetCore/WebHost.cs#L178

   logging.AddConfiguration(hostingContext.Configuration.GetSection("Logging"));

or I assumed that config would take care of it here ...

https://github.com/aspnet/Logging/blob/1ec418937ddb6bbcc83653e90b89285da9eb2a62/src/Microsoft.Extensions.Logging.Console/ConfigurationConsoleLoggerSettings.cs#L27-L35

... but scopes aren't active unless I explicitly set ...

.ConfigureLogging((hostingContext, logging) =>
{
    logging.AddConsole(options => options.IncludeScopes = true);
})

RE: ...

https://github.com/aspnet/Logging/blob/1ec418937ddb6bbcc83653e90b89285da9eb2a62/src/Microsoft.Extensions.Logging.Console/ConfigurationConsoleLoggerSettings.cs#L27

I wondered if that should be ...

var value = _configuration["Logging:IncludeScopes"];

... but even moving "IncludeScopes" up one level doesn't work ...

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

No 🎲 🎲 with this either ...

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

[BrennanConroy]

I believe IncludeScopes isn't working from configuration files in 2.0.0, but has been fixed in latest dev. Although it now lives under the specific logger, so your last example should work in 2.1.0-*

[guardrex]

@BrennanConroy Thanks. I'll make a small modification to the Logging topic to compensate for the time being. The current language doesn't call it out clearly.

@scottaddie @Rick-Anderson I'll add the update for the Logging topic to the LoggerMessage PR, which should be up soon. The sample is almost finished, and the topic is a one-day write-up. Should have it Tuesday ... Wednesday at the latest.