From 3b8cee76696ff600613af36b431259132dbe089e Mon Sep 17 00:00:00 2001
From: Reiley Yang <reyang@microsoft.com>
Date: Thu, 25 Jan 2024 10:02:54 -0800
Subject: [PATCH] [docs] Logger management guidance (#5249)

Co-authored-by: Cijo Thomas <cijo.thomas@gmail.com>
Co-authored-by: Mikel Blanchard <mblanchard@macrosssoftware.com>
---
 docs/logs/README.md | 52 ++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 51 insertions(+), 1 deletion(-)

diff --git a/docs/logs/README.md b/docs/logs/README.md
index 9432718e1..8047b1170 100644
--- a/docs/logs/README.md
+++ b/docs/logs/README.md
@@ -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.