README.md

Serilog.Sinks.RollingFile

Writes Serilog events to a set of text files, one per day.

Important

Deprecation notice: the rolling functionality in this sink has been improved and merged into the Serilog.Sinks.File package. New code should use that package instead.

Migrating to Serilog.Sinks.File

First install the new package, and uninstall this one:

dotnet add package Serilog.Sinks.File
dotnet remove package Serilog.Sinks.RollingFile

Then, replace calls to RollingFile with plain File, removing the {Date} token from the path format, and adding the required rolling interval:

var log = new LoggerConfiguration()
-   .WriteTo.RollingFile("log-{Date}.txt")
+   .WriteTo.File("log-.txt", rollingInterval: RollingInterval.Day)
    .CreateLogger();

See the Serilog.Sinks.File README for more information.

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-20160630.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)

Filename format specifiers

The sink supports three different filename format specifiers:

• {Date} Creates a file per day. Filenames use the yyyyMMdd format.
• {Hour} Creates a file per hour. Filenames use the yyyyMMddHH format.
• {HalfHour} Creates a file per half hour. Filenames use the yyyyMMddHHmm format.

If a log file path is provided without one of the specifiers above, {Date} will be inserted by default.

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 access 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.