|
1 | 1 | # Serilog.Sinks.File [](https://ci.appveyor.com/project/serilog/serilog-sinks-file) [](https://travis-ci.org/serilog/serilog-sinks-file) [](https://www.nuget.org/packages/Serilog.Sinks.File/) [](https://github.com/serilog/serilog/wiki) [](https://gitter.im/serilog/serilog) |
2 | 2 |
|
3 | | -Writes [Serilog](https://serilog.net) events to a text file. |
| 3 | +Writes [Serilog](https://serilog.net) events to one or more text files. |
| 4 | + |
| 5 | +### Getting started |
| 6 | + |
| 7 | +Install the [Serilog.Sinks.File](https://nuget.org/serilog/serilog-sinks-file) package from NuGet: |
| 8 | + |
| 9 | +```powershell |
| 10 | +Install-Package Serilog.Sinks.File |
| 11 | +``` |
| 12 | + |
| 13 | +To configure the sink in C# code, call `WriteTo.File()` during logger configuration: |
4 | 14 |
|
5 | 15 | ```csharp |
6 | 16 | var log = new LoggerConfiguration() |
7 | | - .WriteTo.File("log.txt") |
| 17 | + .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day) |
8 | 18 | .CreateLogger(); |
9 | 19 | ``` |
10 | 20 |
|
| 21 | +This will append the time period to the filename, creating a file set like: |
| 22 | + |
| 23 | +``` |
| 24 | +log20180631.txt |
| 25 | +log20180701.txt |
| 26 | +log20180702.txt |
| 27 | +``` |
| 28 | + |
| 29 | +> **Important**: By default, only one process may write to a log file at a given time. See _Shared log files_ below for information on multi-process sharing. |
| 30 | +
|
| 31 | +### Limits |
| 32 | + |
11 | 33 | To avoid bringing down apps with runaway disk usage the file sink **limits file size to 1GB by default**. The limit can be increased or removed using the `fileSizeLimitBytes` parameter. |
12 | 34 |
|
13 | 35 | ```csharp |
14 | 36 | .WriteTo.File("log.txt", fileSizeLimitBytes: null) |
15 | 37 | ``` |
16 | 38 |
|
17 | | -> **Important:** By default only one process may use a log file at a given time. See _Shared log files_ below if multi-process logging is required. |
| 39 | +For the same reason, only **the most recent 31 files** are retained by default (i.e. one long month). To change or remove this limit, pass the `retainedFileCountLimit` parameter. |
| 40 | + |
| 41 | +```csharp |
| 42 | + .WriteTo.RollingFile("log.txt", rollingInterval: RollingInterval.Day, retainedFileCountLimit: null) |
| 43 | +``` |
| 44 | + |
| 45 | +### Rolling policies |
| 46 | + |
| 47 | +To create a log file per day or other time period, specify a `rollingInterval` as shown in the examples above. |
| 48 | + |
| 49 | +To roll when the file reaches `fileSizeLimitBytes`, specify `rollOnFileSizeLimit`: |
| 50 | + |
| 51 | +```csharp |
| 52 | + .WriteTo.File("log.txt", rollOnFileSizeLimit: true) |
| 53 | +``` |
| 54 | + |
| 55 | +This will create a file set like: |
| 56 | + |
| 57 | +``` |
| 58 | +log.txt |
| 59 | +log_001.txt |
| 60 | +log_002.txt |
| 61 | +``` |
| 62 | + |
| 63 | +Specifying both `rollingInterval` and `rollOnFileSizeLimit` will cause both policies to be applied, while specifying neither will result in all events being written to a single file. |
| 64 | + |
| 65 | +Old files will be cleaned up as per `retainedFileCountLimit` - the default is 31. |
| 66 | + |
| 67 | +### XML `<appSettings>` configuration |
| 68 | + |
| 69 | +To use the file sink with the [Serilog.Settings.AppSettings](https://github.com/serilog/serilog-settings-appsettings) package, first install that package if you haven't already done so: |
| 70 | + |
| 71 | +```powershell |
| 72 | +Install-Package Serilog.Settings.AppSettings |
| 73 | +``` |
| 74 | + |
| 75 | +Instead of configuring the logger in code, call `ReadFrom.AppSettings()`: |
| 76 | + |
| 77 | +```csharp |
| 78 | +var log = new LoggerConfiguration() |
| 79 | + .ReadFrom.AppSettings() |
| 80 | + .CreateLogger(); |
| 81 | +``` |
| 82 | + |
| 83 | +In your application's `App.config` or `Web.config` file, specify the file sink assembly and required path format under the `<appSettings>` node: |
| 84 | + |
| 85 | +```xml |
| 86 | +<configuration> |
| 87 | + <appSettings> |
| 88 | + <add key="serilog:using:File" value="Serilog.Sinks.File" /> |
| 89 | + <add key="serilog:write-to:File.pathFormat" value="log.txt" /> |
| 90 | +``` |
| 91 | + |
| 92 | +The parameters that can be set through the `serilog:write-to:File` keys are the method parameters accepted by the `WriteTo.File()` configuration method. This means, for example, that the `fileSizeLimitBytes` parameter can be set with: |
| 93 | + |
| 94 | +```xml |
| 95 | + <add key="serilog:write-to:File.fileSizeLimitBytes" value="1234567" /> |
| 96 | +``` |
| 97 | + |
| 98 | +Omitting the `value` will set the parameter to `null`: |
18 | 99 |
|
19 | | -### `<appSettings>` configuration |
| 100 | +```xml |
| 101 | + <add key="serilog:write-to:File.fileSizeLimitBytes" /> |
| 102 | +``` |
20 | 103 |
|
21 | | -The sink can be configured in XML [app-settings format](https://github.com/serilog/serilog/wiki/AppSettings) if the _Serilog.Settings.AppSettings_ package is in use: |
| 104 | +In XML and JSON configuration formats, environment variables can be used in setting values. This means, for instance, that the log file path can be based on `TMP` or `APPDATA`: |
22 | 105 |
|
23 | 106 | ```xml |
24 | | -<add key="serilog:using:File" value="Serilog.Sinks.File" /> |
25 | | -<add key="serilog:write-to:File.path" value="log.txt" /> |
26 | | -<add key="serilog:write-to:File.fileSizeLimitBytes" value="" /> |
| 107 | + <add key="serilog:write-to:File.path" value="%APPDATA%\MyApp\log.txt" /> |
| 108 | +``` |
| 109 | + |
| 110 | +### JSON `appsettings.json` configuration |
| 111 | + |
| 112 | +To use the file sink with _Microsoft.Extensions.Configuration_, for example with ASP.NET Core or .NET Core, use the [Serilog.Settings.Configuration](https://github.com/serilog/serilog-settings-configuration) package. First install that package if you have not already done so: |
| 113 | + |
| 114 | +```powershell |
| 115 | +Install-Package Serilog.Settings.Configuration |
| 116 | +``` |
| 117 | + |
| 118 | +Instead of configuring the file directly in code, call `ReadFrom.Configuration()`: |
| 119 | + |
| 120 | +```csharp |
| 121 | +var configuration = new ConfigurationBuilder() |
| 122 | + .AddJsonFile("appsettings.json") |
| 123 | + .Build(); |
| 124 | + |
| 125 | +var logger = new LoggerConfiguration() |
| 126 | + .ReadFrom.Configuration(configuration) |
| 127 | + .CreateLogger(); |
27 | 128 | ``` |
28 | 129 |
|
29 | | -### JSON formatting |
| 130 | +In your `appsettings.json` file, under the `Serilog` node, : |
30 | 131 |
|
31 | | -To emit JSON, rather than plain text, a formatter can be specified: |
| 132 | +```json |
| 133 | +{ |
| 134 | + "Serilog": { |
| 135 | + "WriteTo": [ |
| 136 | + { "Name": "File", "Args": { "path": "log.txt", "rollingInterval": "Day" } } |
| 137 | + ] |
| 138 | + } |
| 139 | +} |
| 140 | +``` |
| 141 | + |
| 142 | +See the XML `<appSettings>` example above for a discussion of available `Args` options. |
| 143 | + |
| 144 | +### Controlling event formatting |
| 145 | + |
| 146 | +The file sink creates events in a fixed text format by default: |
| 147 | + |
| 148 | +``` |
| 149 | +2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms |
| 150 | +``` |
| 151 | + |
| 152 | +The format is controlled using an _output template_, which the file configuration method accepts as an `outputTemplate` parameter. |
| 153 | + |
| 154 | +The default format above corresponds to an output template like: |
32 | 155 |
|
33 | 156 | ```csharp |
34 | | - .WriteTo.File(new JsonFormatter(), "log.txt") |
| 157 | + .WriteTo.File("log.txt", |
| 158 | + outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{u3}] {Message:lj}{NewLine}{Exception}") |
35 | 159 | ``` |
36 | 160 |
|
37 | | -To configure an alternative formatter in XML `<appSettings>`, specify the formatter's assembly-qualified type name as the setting `value`. |
| 161 | +##### JSON event formatting |
| 162 | + |
| 163 | +To write events to the file in an alternative format such as [JSON](https://github.com/serilog/serilog-formatting-compact), pass an `ITextFormatter` as the first argument: |
| 164 | + |
| 165 | +```csharp |
| 166 | + // Install-Package Serilog.Formatting.Compact |
| 167 | + .WriteTo.File(new CompactJsonFormatter(), "log.txt") |
| 168 | +``` |
38 | 169 |
|
39 | 170 | ### Shared log files |
40 | 171 |
|
41 | | -Multiple processes can concurrently write to the same log file if the `shared` parameter is set to `true`: |
| 172 | +To enable multi-process shared log files, set `shared` to `true`: |
42 | 173 |
|
43 | 174 | ```csharp |
44 | 175 | .WriteTo.File("log.txt", shared: true) |
45 | 176 | ``` |
46 | 177 |
|
| 178 | +### Auditing |
| 179 | + |
| 180 | +The file sink can operate as an audit file through `AuditTo`: |
| 181 | + |
| 182 | +```csharp |
| 183 | + .AuditTo.File("audit.txt") |
| 184 | +``` |
| 185 | + |
| 186 | +Only a limited subset of configuration options are currently available in this mode. |
| 187 | + |
47 | 188 | ### Performance |
48 | 189 |
|
49 | 190 | By default, the file sink will flush each event written through it to disk. To improve write performance, specifying `buffered: true` will permit the underlying stream to buffer writes. |
50 | 191 |
|
51 | | -The [Serilog.Sinks.Async](https://github.com/serilog/serilog-sinks-async) package can be used to wrap the file sink and perform all disk accss on a background worker thread. |
| 192 | +The [Serilog.Sinks.Async](https://github.com/serilog/serilog-sinks-async) package can be used to wrap the file sink and perform all disk access on a background worker thread. |
52 | 193 |
|
53 | 194 | _Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._ |
0 commit comments