@@ -40,7 +40,9 @@ benchmark](../../test/Benchmarks/Logs/LogBenchmarks.cs) for more details.
40
40
41
41
:heavy_check_mark : You should always use the
42
42
[ ` 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
44
46
[ Microsoft.Extensions.Logging] ( https://www.nuget.org/packages/Microsoft.Extensions.Logging/ )
45
47
package, regardless of the .NET runtime version being used:
46
48
@@ -103,3 +105,45 @@ logger.LogInformation("Hello from {food} {price}.", food, price);
103
105
104
106
Refer to the [ logging performance
105
107
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