Serilog.Sinks.File.GzArchive 1.1.10

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Core 3.1 This package targets .NET Core 3.1. The package is compatible with this framework or higher. .NET Standard 1.5 This package targets .NET Standard 1.5. The package is compatible with this framework or higher. 
dotnet add package Serilog.Sinks.File.GzArchive --version 1.1.10
NuGet\Install-Package Serilog.Sinks.File.GzArchive -Version 1.1.10
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Serilog.Sinks.File.GzArchive" Version="1.1.10" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Serilog.Sinks.File.GzArchive --version 1.1.10
#r "nuget: Serilog.Sinks.File.GzArchive, 1.1.10"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install Serilog.Sinks.File.GzArchive as a Cake Addin
#addin nuget:?package=Serilog.Sinks.File.GzArchive&version=1.1.10

// Install Serilog.Sinks.File.GzArchive as a Cake Tool
#tool nuget:?package=Serilog.Sinks.File.GzArchive&version=1.1.10

Serilog.Sinks.File.GzArchive Build status NuGet Version Documentation Join the chat at https://gitter.im/serilog/serilog

A FileLifecycleHooks-based plugin for the Serilog FileEx Sink that works with rolling log files, archiving completed log files before they are deleted or being rolled by Serilog's retention mechanism.

The following archive methods are supported:

  • Compress logs in the same directory (using GZip compression)
  • Copying logs to another directory
  • Compress logs (using GZip compression) and write them to another directory
  • Compress the current log stream (using GZip compression)

Getting started

Install the Serilog.Sinks.File.GzArchive package from NuGet:

Install-Package Serilog.Sinks.File.GzArchive

To enable archiving, use one of the new LoggerSinkConfiguration extensions that has a FileLifecycleHooks argument, and create a new FileArchiveRollingHooks. For example, to write GZip compressed logs to another directory (the directory will be created if it doesn't already exist):

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", hooks: new FileArchiveRollingHooks(CompressionLevel.SmallestSize, targetDirectory: "C:\\My\\Archive\\Path"))
    .CreateLogger();

Or to copy logs as-is to another directory:

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", hooks: new FileArchiveRollingHooks(CompressionLevel.NoCompression, targetDirectory: "C:\\My\\Archive\\Path"))
    .CreateLogger();

Or to write GZip compressed logs to the same directory the logs are written to:

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", hooks: new FileArchiveRollingHooks(CompressionLevel.SmallestSize))
    .CreateLogger();

If you want to configure a custom rolling date format, Set the parameter fileNameFormat to a date format string.

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", hooks: new FileArchiveRollingHooks(CompressionLevel.SmallestSize), targetDirectory: "C:\\My\\Archive\\Path", fileNameFormat: "_yyyy-MM-dd")
    .CreateLogger();

This will append the date and time format to the filename using the custom format, create a archive set like:

log_2018-06-31.gz
log_2018-07-01.gz
log_2018-07-02.gz

If you want to use the log file last write time as the rolling date and time instead of the checkpoint, Set the parameter useLastWriteAsTimestamp to true.

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", "_yyyy-MM-dd", rollingInterval: RollingInterval.Day, useLastWriteAsTimestamp: true, hooks: new FileArchiveRollingHooks(CompressionLevel.SmallestSize), targetDirectory: "C:\\My\\Archive\\Path", useLastWriteAsTimestamp: true, fileNameFormat: "_yyyy-MM-dd")
    .CreateLogger();

This will append the last write time for the datetime format, create a archive set like:

log_2018-06-31.gz
log_2018-07-01.gz
log_2018-07-02.gz

If you want to configure a custom scenario for archiving, Set the parameter compressScenario to a CompressScenario enum value.

Log.Logger = new LoggerConfiguration()
    .WriteTo.FileEx("log.txt", hooks: new FileArchiveRollingHooks(CompressionLevel.SmallestSize), targetDirectory: "C:\\My\\Archive\\Path", compressScenario: CompressScenario.OnDelete)
    .CreateLogger();

Available Values for CompressScenario:

CompressScenario.OnDelete
CompressScenario.OnRole
CompressScenario.CompressStream

Note that you cannot set CompressScenario.OnDelete or CompressScenario.OnRolle with CompressScenario.CompressStream together.

Note that archival only works with rolling log files, as files are only deleted or being rolled by Serilog's rolling file retention mechanism. As is standard with Serilog, it's important to call Log.CloseAndFlush(); before your application ends.

Token Replacement

The targetDirectory constructor parameter supports replacement of tokens at runtime.

Tokens take the form {Name:FormatString}, where Name is the name of a supported token, and FormatString defines how the token value should be formatted.

At present, 2 tokens are supported, UtcDate and Date. These use standard .NET date format strings to insert components of the current date/time into the path. For example, you may wish to organise archived files into folders based on the current year and month:

new FileArchiveRollingHooks(CompressionLevel.SmallestSize, "C:\\Archive\\{UtcDate:yyyy}\\{UtcDate:MM}")

Archiving policies

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():

using Serilog.Sinks.File.GzArchive;

namespace MyApp.Logging
{
    public class SerilogHooks
    {
        public static FileArchiveRollingHooks MyFileArchiveRollingHooks => new FileArchiveRollingHooks(CompressionLevel.SmallestSize, "C:\\My\\Archive\\Path");
    }
}

In your appsettings.json file, under the Serilog node, The hooks argument should be configured as follows:

{
  "Serilog": {
    "WriteTo": [
      {
        "Name": "FileEx",
        "Args": {
          "path": "log.txt",
          "fileSizeLimitBytes": 10485760,
          "rollOnFileSizeLimit": true,
          "retainedFileCountLimit": 5,
          "hooks": "MyApp.Logging.SerilogHooks::MyFileArchiveRollingHooks, MyApp"
        }
      }
    ]
  }
}

To break this down a bit, what you are doing is specifying the fully qualified type name of the static class that provides your MyFileArchiveRollingHooks, using Serilog.Settings.Configuration's special :: syntax to point to the MyFileArchiveRollingHooks member.

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

About FileLifecycleHooks

FileLifecycleHooks is a Serilog File Sink mechanism that allows hooking into log file lifecycle events, enabling scenarios such as wrapping the Serilog output stream in another stream, or capturing files before they are deleted or being rolled by Serilog's retention mechanism.

Copyright © 2023 Ashkan Shirian and cocowalla - Provided under the Apache License, Version 2.0.

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  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. 
.NET Core netcoreapp1.0 was computed.  netcoreapp1.1 was computed.  netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 is compatible. 
.NET Standard netstandard1.5 is compatible.  netstandard1.6 is compatible.  netstandard2.0 is compatible.  netstandard2.1 is compatible. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen30 was computed.  tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
1.1.10 148 2/14/2024
1.1.9 90 2/14/2024
1.1.8 186 12/14/2023
1.1.7 184 11/14/2023
1.1.6 1,602 7/16/2023
1.1.5 179 7/9/2023
1.1.4 170 6/25/2023
1.1.3 185 6/25/2023
1.1.2 162 6/18/2023
1.1.1 151 6/17/2023
1.1.0 162 6/16/2023
1.0.7 151 6/16/2023
1.0.6 173 6/14/2023
1.0.5 176 6/13/2023
1.0.4 154 6/13/2023

- Removed the null check to have the possibility to use retainedFileCountLimit and CompressionLevel.NoCompression
     - Added the targetDirectory null check if using no compression