https://github.com/serilog/serilog-sinks-rollingfile
Deprecated: new applications should use https://github.com/serilog/serilog-sinks-file instead
https://github.com/serilog/serilog-sinks-rollingfile
Last synced: 2 months ago
JSON representation
Deprecated: new applications should use https://github.com/serilog/serilog-sinks-file instead
- Host: GitHub
- URL: https://github.com/serilog/serilog-sinks-rollingfile
- Owner: serilog
- License: apache-2.0
- Created: 2016-03-09T06:03:24.000Z (over 9 years ago)
- Default Branch: dev
- Last Pushed: 2024-06-22T22:33:03.000Z (about 1 year ago)
- Last Synced: 2025-04-14T23:54:25.930Z (2 months ago)
- Language: C#
- Homepage:
- Size: 96.7 KB
- Stars: 61
- Watchers: 14
- Forks: 32
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
README
# Serilog.Sinks.RollingFile [](https://ci.appveyor.com/project/serilog/serilog-sinks-rollingfile) [](https://www.nuget.org/packages/Serilog.Sinks.RollingFile/) [](https://github.com/serilog/serilog/wiki)
Writes [Serilog](https://serilog.net) 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_](https://github.com/serilog/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:
```diff
var log = new LoggerConfiguration()
- .WriteTo.RollingFile("log-{Date}.txt")
+ .WriteTo.File("log-.txt", rollingInterval: RollingInterval.Day)
.CreateLogger();
```
See the [`Serilog.Sinks.File` README](https://github.com/serilog/serilog-sinks-file) for more information.
### Getting started
Install the [Serilog.Sinks.RollingFile](https://nuget.org/packages/serilog.sinks.rollingfile) package from NuGet:
```powershell
Install-Package Serilog.Sinks.RollingFile
```
To configure the sink in C# code, call `WriteTo.RollingFile()` during logger configuration:
```csharp
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.
```csharp
.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.
```csharp
.WriteTo.RollingFile("log-{Date}.txt", retainedFileCountLimit: null)
```
### XML `` configuration
To use the rolling 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:
```powershell
Install-Package Serilog.Settings.AppSettings
```
Instead of configuring the logger in code, call `ReadFrom.AppSettings()`:
```csharp
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 `` node:
```xml
```
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:
```xml
```
Omitting the `value` will set the parameter to `null`:
```xml
```
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`:
```xml
```
### 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](https://github.com/serilog/serilog-settings-configuration) package. First install that package if you have not already done so:
```powershell
Install-Package Serilog.Settings.Configuration
```
Instead of configuring the rolling file directly in code, call `ReadFrom.Configuration()`:
```csharp
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, :
```json
{
"Serilog": {
"WriteTo": [
{ "Name": "RollingFile", "Args": { "pathFormat": "log-{Date}.txt" } }
]
}
}
```
See the XML `` 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:
```csharp
.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:
```csharp
.WriteTo.RollingFile(new JsonFormatter(), "log-{Date}.txt")
```
### Shared log files
To enable multi-process shared log files, set `shared` to `true`:
```csharp
.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](https://github.com/serilog/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](https://github.com/BedeGaming/sinks-rollingfile) if your needs aren't met by the default version.
_Copyright © 2016 Serilog Contributors - Provided under the [Apache License, Version 2.0](http://apache.org/licenses/LICENSE-2.0.html)._