Pacem.Extensions.Logging.FileSystem 0.10.13

FileSystem Logging Extensions

⚗️ ==Experimental==

⚠️ Experimental libs are discouraged to use in production.

About

Pacem.Extensions.Logging.FileSystem provides extensions to write your logs to plain text files, with configurable line formatting and file-splitting (by date, level, category or any structured log value).

Log entries are queued and written by a background consumer, so logging calls never block on disk I/O.

ℹ️ This package was previously published as Pacem.Extensions.Logging.File. Replace that package reference — and any using Pacem.Extensions.Logging.File; — with the .FileSystem equivalents.

The following paragraphs exemplify the library utilization given common use cases.

How to

Add the relevant logger provider to the logging builder (e.g. ILoggingBuilder) and configure it through FileSystemLoggerOptions:

// Program.cs
builder.Logging.AddPacemFileSystemLogging(options =>
{
    // required: the folder log files are written into (created on first write)
    options.RootFolderPath = "/var/log/myapp";
});

With the defaults, an information entry from category MyApp.Worker lands in

/var/log/myapp/20260903_Information_log.txt

as the line

[2026-09-03T10:15:30.1234567+02:00] - Information - MyApp.Worker: Job started

Options

File-splitting criteria

FileSplitCriteria is an ordered collection of strings. Each entry contributes one segment to the file-name prefix. Well-known values are exposed on KnownFileSplitCriteria:

ℹ️ Any other string is treated as a structured-log-value key: the logger looks it up among the message placeholders and, when found, uses its value as the segment (whitespace replaced with _).

builder.Logging.AddPacemFileSystemLogging(options =>
{
    options.RootFolderPath = "/var/log/myapp";

    // one file per tenant per day, e.g. 20260903_acme_log.txt
    options.FileSplitCriteria.Clear();
    options.FileSplitCriteria.Add(KnownFileSplitCriteria.LocalDate);
    options.FileSplitCriteria.Add("tenant");

    // cap each file at 5 MB and roll (20260903_acme_log001.txt, ...002.txt, ...)
    options.FileSizeLimit = 5 * 1024 * 1024;

    // only persist warnings and above
    options.Filter = log => log.LogLevel >= LogLevel.Warning;
});

// "tenant" is resolved from the structured placeholder
logger.LogWarning("Quota exceeded for {tenant}", "acme");

Plans for version next

Rolling retention (max file count / max age) and an opt-in JSON line format.