|
1 | 1 | # Serilog.AspNetCore [](https://ci.appveyor.com/project/serilog/serilog-aspnetcore) [](https://www.nuget.org/packages/Serilog.AspNetCore/) |
2 | 2 |
|
| 3 | +Serilog logging for ASP.NET Core. This package routes ASP.NET Core log messages through Serilog, so you can get information about ASP.NET's internal operations written to the same Serilog sinks as your application events. |
3 | 4 |
|
4 | | -Serilog logging for ASP.NET Core. This package routes ASP.NET Core log messages through Serilog, so you can get information about ASP.NET's internal operations logged to the same Serilog sinks as your application events. |
| 5 | +With _Serilog.AspNetCore_ installed and configured, you can write log messages directly through Serilog or any `ILogger` interface injected by ASP.NET. All loggers will use the same underlying implementation, levels, and destinations. |
5 | 6 |
|
6 | 7 | ### Instructions |
7 | 8 |
|
8 | 9 | **First**, install the _Serilog.AspNetCore_ [NuGet package](https://www.nuget.org/packages/Serilog.AspNetCore) into your app. You will need a way to view the log messages - _Serilog.Sinks.Console_ writes these to the console; there are [many more sinks available](https://www.nuget.org/packages?q=Tags%3A%22serilog%22) on NuGet. |
9 | 10 |
|
10 | | -```powershell |
11 | | -Install-Package Serilog.AspNetCore -DependencyVersion Highest |
12 | | -Install-Package Serilog.Sinks.Console |
| 11 | +```shell |
| 12 | +dotnet add package Serilog.AspNetCore |
| 13 | +dotnet add package Serilog.Sinks.Console |
13 | 14 | ``` |
14 | 15 |
|
15 | 16 | **Next**, in your application's _Program.cs_ file, configure Serilog first. A `try`/`catch` block will ensure any configuration issues are appropriately logged: |
@@ -82,11 +83,82 @@ Tip: to see Serilog output in the Visual Studio output window when running under |
82 | 83 |
|
83 | 84 | A more complete example, showing _appsettings.json_ configuration, can be found in [the sample project here](https://github.com/serilog/serilog-aspnetcore/tree/dev/samples/EarlyInitializationSample). |
84 | 85 |
|
85 | | -### Using the package |
| 86 | +### Request logging |
86 | 87 |
|
87 | | -With _Serilog.AspNetCore_ installed and configured, you can write log messages directly through Serilog or any `ILogger` interface injected by ASP.NET. All loggers will use the same underlying implementation, levels, and destinations. |
| 88 | +The package includes middleware for smarter HTTP request logging. The default request logging implemented by ASP.NET Core is noisy, with multiple events emitted per request. The included middleware condenses these into a single event that carries method, path, status code, and timing information. |
| 89 | + |
| 90 | +As text, this has a format like: |
| 91 | + |
| 92 | +``` |
| 93 | +[16:05:54 INF] HTTP GET / responded 200 in 227.3253 ms |
| 94 | +``` |
| 95 | + |
| 96 | +Or [as JSON](https://github.com/serilog/serilog-formatting-compact): |
| 97 | + |
| 98 | +```json |
| 99 | +{ |
| 100 | + "@t":"2019-06-26T06:05:54.6881162Z", |
| 101 | + "@mt":"HTTP {RequestMethod} {RequestPath} responded {StatusCode} in {Elapsed:0.0000} ms", |
| 102 | + "@r":["224.5185"], |
| 103 | + "RequestMethod":"GET", |
| 104 | + "RequestPath":"/", |
| 105 | + "StatusCode":200, |
| 106 | + "Elapsed":224.5185, |
| 107 | + "RequestId":"0HLNPVG1HI42T:00000001", |
| 108 | + "CorrelationId":null, |
| 109 | + "ConnectionId":"0HLNPVG1HI42T" |
| 110 | +} |
| 111 | +``` |
| 112 | + |
| 113 | +To enable the middleware, first change the minimum level for `Microsoft` to `Warning` in your logger configuration or _appsettings.json_ file: |
| 114 | + |
| 115 | +```csharp |
| 116 | + .MinimumLevel.Override("Microsoft", LogEventLevel.Warning) |
| 117 | +``` |
| 118 | + |
| 119 | +Then, in your application's _Startup.cs_, add the middleware with `UseSerilogRequestLogging()`: |
| 120 | + |
| 121 | +```csharp |
| 122 | + public void Configure(IApplicationBuilder app, IHostingEnvironment env) |
| 123 | + { |
| 124 | + if (env.IsDevelopment()) |
| 125 | + { |
| 126 | + app.UseDeveloperExceptionPage(); |
| 127 | + } |
| 128 | + else |
| 129 | + { |
| 130 | + app.UseExceptionHandler("/Home/Error"); |
| 131 | + } |
| 132 | + |
| 133 | + app.UseSerilogRequestLogging(); // <-- Add this line |
| 134 | +
|
| 135 | + // Other app configuration |
| 136 | +``` |
| 137 | + |
| 138 | +It's important that the `UseSerilogRequestLogging()` call appears _before_ handlers such as MVC. The middleware will not time or log components that appear before it in the pipeline. (This can be utilized to exclude noisy handlers from logging, such as `UseStaticFiles()`, by placing `UseSerilogRequestLogging()` after them.) |
| 139 | + |
| 140 | +During request processing, additional properties can be attached to the completion event using `IDiagnosticContext.Set()`: |
| 141 | + |
| 142 | +```csharp |
| 143 | + public class HomeController : Controller |
| 144 | + { |
| 145 | + readonly IDiagnosticContext _diagnosticContext; |
| 146 | + |
| 147 | + public HomeController(IDiagnosticContext diagnosticContext) |
| 148 | + { |
| 149 | + _diagnosticContext = diagnosticContext ?? throw new ArgumentNullException(nameof(diagnosticContext)); |
| 150 | + } |
| 151 | + |
| 152 | + public IActionResult Index() |
| 153 | + { |
| 154 | + // The request completion event will carry this property |
| 155 | + _diagnosticContext.Set("CatalogLoadTime", 1423); |
| 156 | + |
| 157 | + return View(); |
| 158 | + } |
| 159 | +``` |
88 | 160 |
|
89 | | -**Tip:** change the minimum level for `Microsoft` to `Warning` and plug in this [custom logging middleware](https://github.com/datalust/serilog-middleware-example/blob/master/src/Datalust.SerilogMiddlewareExample/Diagnostics/SerilogMiddleware.cs) to clean up request logging output and record more context around errors and exceptions. |
| 161 | +This pattern has the advantage of reducing the number of log events that need to be constructed, transmitted, and stored per HTTP request. Having many properties on the same event can also make correlation of request details and other data easier. |
90 | 162 |
|
91 | 163 | ### Inline initialization |
92 | 164 |
|
|
0 commit comments