Skip to content

Commit 1b0add0

Browse files
committed
logger management guidance
1 parent eab0a7c commit 1b0add0

File tree

1 file changed

+45
-1
lines changed

1 file changed

+45
-1
lines changed

docs/logs/README.md

Lines changed: 45 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,9 @@ benchmark](../../test/Benchmarks/Logs/LogBenchmarks.cs) for more details.
4040

4141
:heavy_check_mark: You should always use the
4242
[`ILogger`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
43-
interface from the latest stable version of
43+
interface (including
44+
[`ILogger<TCategoryName>`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1))
45+
from the latest stable version of
4446
[Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging/)
4547
package, regardless of the .NET runtime version being used:
4648

@@ -103,3 +105,45 @@ logger.LogInformation("Hello from {food} {price}.", food, price);
103105

104106
Refer to the [logging performance
105107
benchmark](../../test/Benchmarks/Logs/LogBenchmarks.cs) for more details.
108+
109+
## Logger Management
110+
111+
In order to use
112+
[`ILogger`](https://docs.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger)
113+
interface (including
114+
[`ILogger<TCategoryName>`](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.ilogger-1)),
115+
you need to first get a logger. How to get a logger depends on two things:
116+
117+
* The type of application you are building.
118+
* The place where you want to log.
119+
120+
Here is the rule of thumb:
121+
122+
* If you are building an application with [dependency injection
123+
(DI)](https://learn.microsoft.com/dotnet/core/extensions/dependency-injection)
124+
(e.g. [ASP.NET Core](https://learn.microsoft.com/aspnet/core) and [.NET
125+
Worker](https://learn.microsoft.com/dotnet/core/extensions/workers)), in most
126+
cases you should use the logger provided by DI, there are special cases when
127+
you want log before DI logging pipeline is available or after DI logging
128+
pipeline is disposed. Refer to the [Getting Started with OpenTelemetry .NET
129+
Logs in 5 Minutes - ASP.NET Core
130+
Application](./getting-started-aspnetcore/README.md) tutorial to learn more.
131+
* If you are building an application without DI, create a `LoggerFactory`
132+
instance and configure OpenTelemetry to work with it. Refer to the [Getting
133+
Started with OpenTelemetry .NET Logs in 5 Minutes - Console
134+
Application](./getting-started-console/README.md) tutorial to learn more.
135+
136+
:stop_sign: You should avoid creating `LoggerFactory` instances too frequently,
137+
`LoggerFactory` is fairly expensive and meant to be reused throughout the
138+
application. For most applications, one `LoggerFactory` instance per process
139+
should be sufficient.
140+
141+
:heavy_check_mark: You should properly manage the lifecycle of
142+
[LoggerFactory](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.loggerfactory)
143+
instances if they are created by you.
144+
145+
* If you don't dispose the `LoggerFactory` instance before the application ends,
146+
logs might get dropped due to the lack of proper flush.
147+
* If you dispose the `LoggerFactory` instance too early, any subsequent logging
148+
API invocation associated with the logger factory could become no-op (i.e. no
149+
logs will be emitted).

0 commit comments

Comments
 (0)