Repository files navigation

WritesSerilog events to one or more text files.

Install theSerilog.Sinks.File package from NuGet:

dotnet add package Serilog.Sinks.File

To configure the sink in C# code, callWriteTo.File() during logger configuration:

varlog=newLoggerConfiguration().WriteTo.File("log.txt",rollingInterval:RollingInterval.Day).CreateLogger();

This will append the time period to the filename, creating a file set like:

log20180631.txtlog20180701.txtlog20180702.txt

Important: By default, only one process may write to a log file at a given time. SeeShared log files below for information on multi-process sharing.

To avoid bringing down apps with runaway disk usage the file sinklimits 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 below).

The limit can be changed or removed using thefileSizeLimitBytes parameter.

.WriteTo.File("log.txt",fileSizeLimitBytes:null)

For the same reason, onlythe most recent 31 files are retained by default (i.e. one long month). To change or remove this limit, pass theretainedFileCountLimit parameter.

.WriteTo.File("log.txt",rollingInterval:RollingInterval.Day,retainedFileCountLimit:null)

To create a log file per day or other time period, specify arollingInterval as shown in the examples above.

To roll when the file reachesfileSizeLimitBytes, specifyrollOnFileSizeLimit:

.WriteTo.File("log.txt",rollOnFileSizeLimit:true)

This will create a file set like:

log.txtlog_001.txtlog_002.txt

Specifying bothrollingInterval androllOnFileSizeLimit will cause both policies to be applied, while specifying neither will result in all events being written to a single file.

Old files will be cleaned up as perretainedFileCountLimit - the default is 31.

To use the file sink with theSerilog.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, callReadFrom.AppSettings():

varlog=newLoggerConfiguration().ReadFrom.AppSettings().CreateLogger();

In your application'sApp.config orWeb.config file, specify the file sink assembly and required path format under the<appSettings> node:

<configuration>  <appSettings>    <addkey="serilog:using:File"value="Serilog.Sinks.File" />    <addkey="serilog:write-to:File.path"value="log.txt" />

The parameters that can be set through theserilog:write-to:File keys are the method parameters accepted by theWriteTo.File() configuration method. This means, for example, that thefileSizeLimitBytes parameter can be set with:

    <addkey="serilog:write-to:File.fileSizeLimitBytes"value="1234567" />

Omitting thevalue will set the parameter tonull:

    <addkey="serilog:write-to:File.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 onTMP orAPPDATA:

    <addkey="serilog:write-to:File.path"value="%APPDATA%\MyApp\log.txt" />

To use the file sink withMicrosoft.Extensions.Configuration, for example with ASP.NET Core or .NET Core, use theSerilog.Settings.Configuration package. First install that package if you have not already done so:

Install-Package Serilog.Settings.Configuration

Instead of configuring the file directly in code, callReadFrom.Configuration():

varconfiguration=newConfigurationBuilder().AddJsonFile("appsettings.json").Build();varlogger=newLoggerConfiguration().ReadFrom.Configuration(configuration).CreateLogger();

In yourappsettings.json file, under theSerilog node, :

{"Serilog": {"WriteTo": [      {"Name":"File","Args": {"path":"log.txt","rollingInterval":"Day" } }    ]  }}

See the XML<appSettings> example above for a discussion of availableArgs options.

The file sink creates events in a fixed text format by default:

2018-07-06 09:02:17.148 +10:00 [INF] HTTP GET / responded 200 in 1994 ms

The format is controlled using anoutput template, which the file configuration method accepts as anoutputTemplate parameter.

The default format above corresponds to an output template like:

.WriteTo.File("log.txt",outputTemplate:"{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{NewLine}{Exception}")

To write events to the file in an alternative format such asJSON, pass anITextFormatter as the first argument:

// Install-Package Serilog.Formatting.Compact.WriteTo.File(newCompactJsonFormatter(),"log.txt")

To enable multi-process shared log files, setshared totrue:

.WriteTo.File("log.txt",shared:true)

The file sink can operate as an audit file throughAuditTo:

.AuditTo.File("audit.txt")

Only a limited subset of configuration options are currently available in this mode.

By default, the file sink will flush each event written through it to disk. To improve write performance, specifyingbuffered: true will permit the underlying stream to buffer writes.

TheSerilog.Sinks.Async package can be used to wrap the file sink and perform all disk access on a background worker thread.

FileLifecycleHooks provide an extensibility point that allows hooking into different parts of the life cycle of a log file.

You can create a hook by extending fromFileLifecycleHooks and overriding theOnFileOpened and/orOnFileDeleting methods.

• 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)

• 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

Available hooks:

• serilog-sinks-file-header: writes a header to the start of each log file
• serilog-sinks-file-gzip: compresses logs as they are written, using streaming GZIP compression
• serilog-sinks-file-archive: archives obsolete rolling log files before they are deleted by Serilog's retention mechanism

Copyright © 2016 Serilog Contributors - Provided under theApache License, Version 2.0.