Serilog.Sinks.ZipFile
3.1.1
dotnet add package Serilog.Sinks.ZipFile --version 3.1.1
NuGet\Install-Package Serilog.Sinks.ZipFile -Version 3.1.1
<PackageReference Include="Serilog.Sinks.ZipFile" Version="3.1.1" />
paket add Serilog.Sinks.ZipFile --version 3.1.1
#r "nuget: Serilog.Sinks.ZipFile, 3.1.1"
// Install Serilog.Sinks.ZipFile as a Cake Addin
#addin nuget:?package=Serilog.Sinks.ZipFile&version=3.1.1
// Install Serilog.Sinks.ZipFile as a Cake Tool
#tool nuget:?package=Serilog.Sinks.ZipFile&version=3.1.1
Serilog.Sinks.ZipFile
Writes Serilog events to a text file, as well as supplemntal log files, into a zip archive.
Getting started
Install the Serilog.Sinks.ZipFile package from NuGet:
Install-Package Serilog.Sinks.ZipFile
To configure the sink in C# code, call WriteTo.ZipFile()
during logger configuration:
var log = new LoggerConfiguration()
.WriteTo.ZipFile("log.txt", rollingInterval: RollingInterval.Day)
.CreateLogger();
This will append the time period to the filename, creating a file set like:
log20180631.txt
log20180701.txt
log20180702.txt
Important: Only one process may write to a log file at a given time.
Logging Files into the Zip
Supplemental log files are detected by pattern matching. If the logged type contains properties named 'filename' and 'filedata' (case insensative) with types string
and byte[]
respectively, the type is destructured into a format that ZipFileSink can parse, and the file is added to the zip. File names are prepended with the timestamp. By defauly, files are compressed with CompressionLevel.Fastest
. If the logged object contains a property of type System.IO.Compression.CompressionLevel
, that compression level will be used instead.
Example:
Serilog.Log.Logger.Information(
"{@file}",
new
{
filename = "somefile.txt",
filedata = System.Text.Encoding.UTF8.GetBytes("Some text in a file")
});
Rolling policies
To create a log file per day or other time period, specify a rollingInterval
as shown in the examples above.
Specifying both rollingInterval
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 per retainedFileCountLimit
- the default is 31.
XML <appSettings>
configuration
To use the 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 file sink assembly and required path format under the <appSettings>
node:
<configuration>
<appSettings>
<add key="serilog:using:ZipFile" value="Serilog.Sinks.ZipFile" />
<add key="serilog:write-to:ZipFile.path" value="log.txt" />
The parameters that can be set through the serilog:write-to:ZipFile
keys are the method parameters accepted by the WriteTo.ZipFile()
configuration method.
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:ZipFile.path" value="%APPDATA%\MyApp\log.txt" />
JSON appsettings.json
configuration
To use the 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 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": "ZipFile", "Args": { "path": "log.txt", "rollingInterval": "Day" } }
]
}
}
See the XML <appSettings>
example above for a discussion of available Args
options.
Controlling event formatting
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 an output template, which the file configuration method accepts as an outputTemplate
parameter.
The default format above corresponds to an output template like:
.WriteTo.ZipFile("log.txt",
outputTemplate: "{Timestamp:yyyy-MM-dd HH:mm:ss.fff zzz} [{Level:u3}] {Message:lj}{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:
// Install-Package Serilog.Formatting.Compact
.WriteTo.ZipFile(new CompactJsonFormatter(), "log.txt")
Shared log files
To enable multi-process shared log files, set shared
to true
:
.WriteTo.ZipFile("log.txt", shared: true)
Auditing
The file sink can operate as an audit file through AuditTo
:
.AuditTo.ZipFile("audit.txt")
Only a limited subset of configuration options are currently available in this mode.
Performance
By default, the file sink will flush each event written through it to disk.
The Serilog.Sinks.Async package can be used to wrap the file sink and perform all disk access on a background worker thread.
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net8.0 is compatible. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. |
-
net8.0
- Serilog (>= 3.1.1)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories (1)
Showing the top 1 popular GitHub repositories that depend on Serilog.Sinks.ZipFile:
Repository | Stars |
---|---|
rmcrackan/Libation
Libation: Liberate your Library
|