|
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) |
| 1 | +# Serilog.Sinks.File [](https://ci.appveyor.com/project/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://www.nuget.org/packages/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 |
|
11 | | -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. |
| 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 | + |
| 33 | +To avoid bringing down apps with runaway disk usage the file sink **limits file size to 1GB by default**. Once the limit is reached, no further events will be written until the next roll point (see also: [Rolling policies](#rolling-policies) below). |
| 34 | + |
| 35 | +The limit can be changed or removed using the `fileSizeLimitBytes` parameter. |
12 | 36 |
|
13 | 37 | ```csharp |
14 | 38 | .WriteTo.File("log.txt", fileSizeLimitBytes: null) |
| 39 | +``` |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +```csharp |
| 44 | + .WriteTo.File("log.txt", rollingInterval: RollingInterval.Day, retainedFileCountLimit: null) |
| 45 | +``` |
| 46 | + |
| 47 | +### Rolling policies |
| 48 | + |
| 49 | +To create a log file per day or other time period, specify a `rollingInterval` as shown in the examples above. |
| 50 | + |
| 51 | +To roll when the file reaches `fileSizeLimitBytes`, specify `rollOnFileSizeLimit`: |
| 52 | + |
| 53 | +```csharp |
| 54 | + .WriteTo.File("log.txt", rollOnFileSizeLimit: true) |
| 55 | +``` |
| 56 | + |
| 57 | +This will create a file set like: |
| 58 | + |
| 59 | +``` |
| 60 | +log.txt |
| 61 | +log_001.txt |
| 62 | +log_002.txt |
| 63 | +``` |
| 64 | + |
| 65 | +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. |
| 66 | + |
| 67 | +Old files will be cleaned up as per `retainedFileCountLimit` - the default is 31. |
| 68 | + |
| 69 | +### XML `<appSettings>` configuration |
| 70 | + |
| 71 | +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: |
| 72 | + |
| 73 | +```powershell |
| 74 | +Install-Package Serilog.Settings.AppSettings |
| 75 | +``` |
| 76 | + |
| 77 | +Instead of configuring the logger in code, call `ReadFrom.AppSettings()`: |
| 78 | + |
| 79 | +```csharp |
| 80 | +var log = new LoggerConfiguration() |
| 81 | + .ReadFrom.AppSettings() |
| 82 | + .CreateLogger(); |
| 83 | +``` |
| 84 | + |
| 85 | +In your application's `App.config` or `Web.config` file, specify the file sink assembly and required path format under the `<appSettings>` node: |
| 86 | + |
| 87 | +```xml |
| 88 | +<configuration> |
| 89 | + <appSettings> |
| 90 | + <add key="serilog:using:File" value="Serilog.Sinks.File" /> |
| 91 | + <add key="serilog:write-to:File.path" value="log.txt" /> |
15 | 92 | ``` |
16 | 93 |
|
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. |
| 94 | +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: |
18 | 95 |
|
19 | | -### `<appSettings>` configuration |
| 96 | +```xml |
| 97 | + <add key="serilog:write-to:File.fileSizeLimitBytes" value="1234567" /> |
| 98 | +``` |
| 99 | + |
| 100 | +Omitting the `value` will set the parameter to `null`: |
| 101 | + |
| 102 | +```xml |
| 103 | + <add key="serilog:write-to:File.fileSizeLimitBytes" /> |
| 104 | +``` |
20 | 105 |
|
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: |
| 106 | +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 | 107 |
|
23 | 108 | ```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="" /> |
| 109 | + <add key="serilog:write-to:File.path" value="%APPDATA%\MyApp\log.txt" /> |
27 | 110 | ``` |
28 | 111 |
|
29 | | -### JSON formatting |
| 112 | +### JSON `appsettings.json` configuration |
30 | 113 |
|
31 | | -To emit JSON, rather than plain text, a formatter can be specified: |
| 114 | +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: |
| 115 | + |
| 116 | +```powershell |
| 117 | +Install-Package Serilog.Settings.Configuration |
| 118 | +``` |
| 119 | + |
| 120 | +Instead of configuring the file directly in code, call `ReadFrom.Configuration()`: |
32 | 121 |
|
33 | 122 | ```csharp |
34 | | - .WriteTo.File(new JsonFormatter(), "log.txt") |
| 123 | +var configuration = new ConfigurationBuilder() |
| 124 | + .AddJsonFile("appsettings.json") |
| 125 | + .Build(); |
| 126 | + |
| 127 | +var logger = new LoggerConfiguration() |
| 128 | + .ReadFrom.Configuration(configuration) |
| 129 | + .CreateLogger(); |
35 | 130 | ``` |
36 | 131 |
|
37 | | -To configure an alternative formatter in XML `<appSettings>`, specify the formatter's assembly-qualified type name as the setting `value`. |
| 132 | +In your `appsettings.json` file, under the `Serilog` node, : |
| 133 | + |
| 134 | +```json |
| 135 | +{ |
| 136 | + "Serilog": { |
| 137 | + "WriteTo": [ |
| 138 | + { "Name": "File", "Args": { "path": "log.txt", "rollingInterval": "Day" } } |
| 139 | + ] |
| 140 | + } |
| 141 | +} |
| 142 | +``` |
| 143 | + |
| 144 | +See the XML `<appSettings>` example above for a discussion of available `Args` options. |
| 145 | + |
| 146 | +### Controlling event formatting |
| 147 | + |
| 148 | +The file sink creates events in a fixed text format by default: |
| 149 | + |
| 150 | +``` |
| 151 | +2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms |
| 152 | +``` |
| 153 | + |
| 154 | +The format is controlled using an _output template_, which the file configuration method accepts as an `outputTemplate` parameter. |
| 155 | + |
| 156 | +The default format above corresponds to an output template like: |
| 157 | + |
| 158 | +```csharp |
| 159 | + .WriteTo.File("log.txt", |
| 160 | + outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}") |
| 161 | +``` |
| 162 | + |
| 163 | +##### JSON event formatting |
| 164 | + |
| 165 | +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: |
| 166 | + |
| 167 | +```csharp |
| 168 | + // Install-Package Serilog.Formatting.Compact |
| 169 | + .WriteTo.File(new CompactJsonFormatter(), "log.txt") |
| 170 | +``` |
38 | 171 |
|
39 | 172 | ### Shared log files |
40 | 173 |
|
41 | | -Multiple processes can concurrently write to the same log file if the `shared` parameter is set to `true`: |
| 174 | +To enable multi-process shared log files, set `shared` to `true`: |
42 | 175 |
|
43 | 176 | ```csharp |
44 | 177 | .WriteTo.File("log.txt", shared: true) |
45 | 178 | ``` |
46 | 179 |
|
| 180 | +### Auditing |
| 181 | + |
| 182 | +The file sink can operate as an audit file through `AuditTo`: |
| 183 | + |
| 184 | +```csharp |
| 185 | + .AuditTo.File("audit.txt") |
| 186 | +``` |
| 187 | + |
| 188 | +Only a limited subset of configuration options are currently available in this mode. |
| 189 | + |
47 | 190 | ### Performance |
48 | 191 |
|
49 | 192 | 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 | 193 |
|
51 | 194 | 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 | 195 |
|
| 196 | +### Extensibility |
| 197 | +[`FileLifecycleHooks`](https://github.com/serilog/serilog-sinks-file/blob/master/src/Serilog.Sinks.File/Sinks/File/FileLifecycleHooks.cs) provide an extensibility point that allows hooking into different parts of the life cycle of a log file. |
| 198 | + |
| 199 | +You can create a hook by extending from [`FileLifecycleHooks`](https://github.com/serilog/serilog-sinks-file/blob/master/src/Serilog.Sinks.File/Sinks/File/FileLifecycleHooks.cs) and overriding the `OnFileOpened` and/or `OnFileDeleting` methods. |
| 200 | + |
| 201 | +- `OnFileOpened` provides access to the underlying stream that log events are written to, before Serilog begins writing events. You can use this to write your own data to the stream (for example, to write a header row), or to wrap the stream in another stream (for example, to add buffering, compression or encryption) |
| 202 | + |
| 203 | +- `OnFileDeleting` provides a means to work with obsolete rolling log files, *before* they are deleted by Serilog's retention mechanism - for example, to archive log files to another location |
| 204 | + |
| 205 | +Available hooks: |
| 206 | + |
| 207 | +- [serilog-sinks-file-header](https://github.com/cocowalla/serilog-sinks-file-header): writes a header to the start of each log file |
| 208 | +- [serilog-sinks-file-gzip](https://github.com/cocowalla/serilog-sinks-file-gzip): compresses logs as they are written, using streaming GZIP compression |
| 209 | +- [serilog-sinks-file-archive](https://github.com/cocowalla/serilog-sinks-file-archive): archives obsolete rolling log files before they are deleted by Serilog's retention mechanism |
| 210 | + |
53 | 211 | _Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._ |
0 commit comments