Awesome
Serilog.Sinks.RollingFile
![Join the chat at https://gitter.im/serilog/serilog](https://img.shields.io/gitter/room/serilog/serilog.svg)
Writes Serilog events to a set of text files, one per day.
Getting started
Install the Serilog.Sinks.RollingFile package from NuGet:
Install-Package Serilog.Sinks.RollingFile
To configure the sink in C# code, call WriteTo.RollingFile()
during logger configuration:
var log = new LoggerConfiguration()
.WriteTo.RollingFile("log-{Date}.txt")
.CreateLogger();
Log.Information("This will be written to the rolling file set");
The filename should include the {Date}
placeholder, which will be replaced with the date of the events contained in the file. Filenames use the yyyyMMdd
date format so that files can be ordered using a lexicographic sort:
log-20160631.txt
log-20160701.txt
log-20160702.txt
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.
Limits
To avoid bringing down apps with runaway disk usage the rolling file sink limits file size to 1GB by default. The limit can be changed or removed using the fileSizeLimitBytes
parameter.
.WriteTo.RollingFile("log-{Date}.txt", fileSizeLimitBytes: null)
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.
.WriteTo.RollingFile("log-{Date}.txt", retainedFileCountLimit: null)
XML <appSettings>
configuration
To use the rolling file sink with the Serilog.Settings.AppSettings package, first install that package if you haven't already done so:
Install-Package Serilog.Settings.AppSettings
Instead of configuring the logger in code, call ReadFrom.AppSettings()
:
var log = new LoggerConfiguration()
.ReadFrom.AppSettings()
.CreateLogger();
In your application's App.config
or Web.config
file, specify the rolling file sink assembly and required path format under the <appSettings>
node:
<configuration>
<appSettings>
<add key="serilog:using:RollingFile" value="Serilog.Sinks.RollingFile" />
<add key="serilog:write-to:RollingFile.pathFormat" value="log-{Date}.txt" />
The parameters that can be set through the serilog:write-to:RollingFile
keys are the method parameters accepted by the WriteTo.RollingFile()
configuration method. This means, for example, that the fileSizeLimitBytes
parameter can be set with:
<add key="serilog:write-to:RollingFile.fileSizeLimitBytes" value="1234567" />
Omitting the value
will set the parameter to null
:
<add key="serilog:write-to:RollingFile.fileSizeLimitBytes" />
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
:
<add key="serilog:write-to:RollingFile.pathFormat" value="%APPDATA%\MyApp\log-{Date}.txt" />
JSON appsettings.json
configuration
To use the rolling file sink with Microsoft.Extensions.Configuration, for example with ASP.NET Core or .NET Core, use the Serilog.Settings.Configuration package. First install that package if you have not already done so:
Install-Package Serilog.Settings.Configuration
Instead of configuring the rolling file directly in code, call ReadFrom.Configuration()
:
var configuration = new ConfigurationBuilder()
.AddJsonFile("appsettings.json")
.Build();
var logger = new LoggerConfiguration()
.ReadFrom.Configuration(configuration)
.CreateLogger();
In your appsettings.json
file, under the Serilog
node, :
{
"Serilog": {
"WriteTo": [
{ "Name": "RollingFile", "Args": { "pathFormat": "log-{Date}.txt" } }
]
}
}
See the XML <appSettings>
example above for a discussion of available Args
options.
Controlling event formatting
The rolling file sink creates events in a fixed text format by default:
2016-07-06 09:02:17.148 +10:00 [Information] HTTP "GET" "/" responded 200 in 1994 ms
The format is controlled using an output template, which the rolling file configuration method accepts as an outputTemplate
parameter.
The default format above corresponds to an output template like:
.WriteTo.RollingFile("log-{Date}.txt",
outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level}] {Message}{NewLine}{Exception}")
JSON event formatting
To write events to the file in an alternative format such as JSON, pass an ITextFormatter
as the first argument:
.WriteTo.RollingFile(new JsonFormatter(), "log-{Date}.txt")
Shared log files
To enable multi-process shared log files, set shared
to true
:
.WriteTo.RollingFile("log-{Date}.txt", shared: true)
Performance
By default, the rolling 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.
The Serilog.Sinks.Async package can be used to wrap the rolling file sink and perform all disk accss on a background worker thread.
Alternatives
The default rolling file sink is designed to suit most applications. So that we can keep it maintainable and reliable, it does not provide a large range of optional behavior. Check out alternative implemementations like this one if your needs aren't met by the default version.
Copyright © 2016 Serilog Contributors - Provided under the Apache License, Version 2.0.