[docs] Logger management guidance (#5249)

Co-authored-by: Cijo Thomas <cijo.thomas@gmail.com>
Co-authored-by: Mikel Blanchard <mblanchard@macrosssoftware.com>
This commit is contained in:
Reiley Yang 2024-01-25 10:02:54 -08:00 committed by GitHub
parent 0fefe37af9
commit 3b8cee7669
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 51 additions and 1 deletions

View File

@ -40,7 +40,9 @@ benchmark](../../test/Benchmarks/Logs/LogBenchmarks.cs) for more details.
:heavy_check_mark: You should always use the
[`ILogger`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
interface from the latest stable version of
interface (including
[`ILogger<TCategoryName>`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1))
from the latest stable version of
[Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging/)
package, regardless of the .NET runtime version being used:
@ -103,3 +105,51 @@ logger.LogInformation("Hello from {food} {price}.", food, price);
Refer to the [logging performance
benchmark](../../test/Benchmarks/Logs/LogBenchmarks.cs) for more details.
## Logger Management
In order to use
[`ILogger`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
interface (including
[`ILogger<TCategoryName>`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1)),
you need to first get a logger. How to get a logger depends on two things:
* The type of application you are building.
* The place where you want to log.
Here is the rule of thumb:
* If you are building an application with [dependency injection
(DI)](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection)
(e.g. [ASP.NET Core](https://learn.microsoft.com/aspnet/core) and [.NET
Worker](https://learn.microsoft.com/dotnet/core/extensions/workers)), in most
cases you should use the logger provided by DI, there are special cases when
you want log before DI logging pipeline is available or after DI logging
pipeline is disposed. Refer to the [.NET official
document](https://learn.microsoft.com/dotnet/core/extensions/logging#integration-with-hosts-and-dependency-injection)
and [Getting Started with OpenTelemetry .NET Logs in 5 Minutes - ASP.NET Core
Application](./getting-started-aspnetcore/README.md) tutorial to learn more.
* If you are building an application without DI, create a `LoggerFactory`
instance and configure OpenTelemetry to work with it. Refer to the [Getting
Started with OpenTelemetry .NET Logs in 5 Minutes - Console
Application](./getting-started-console/README.md) tutorial to learn more.
:stop_sign: You should avoid creating `LoggerFactory` instances too frequently,
`LoggerFactory` is fairly expensive and meant to be reused throughout the
application. For most applications, one `LoggerFactory` instance per process
would be sufficient.
:heavy_check_mark: You should properly manage the lifecycle of
[LoggerFactory](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.loggerfactory)
instances if they are created by you.
* If you forget to dispose the `LoggerFactory` instance before the application
ends, logs might get dropped due to the lack of proper flush.
* If you dispose the `LoggerFactory` instance too early, any subsequent logging
API invocation associated with the logger factory could become no-op (i.e. no
logs will be emitted).
:heavy_check_mark: You should use the fully qualified class name as the log
category name. Refer to the [.NET official
document](https://learn.microsoft.com/dotnet/core/extensions/logging#log-category)
to learn more.