Pacem.Logging.FileSystem 1.0.0-ricci

FileSystem Logging Extensions

⚗️ ==Experimental==

⚠️ Experimental libs are discouraged to use in production.

About

Pacem.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.Logging.File. Replace that package reference — and any using Pacem.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 FileSplitCriterion entries. Each one has a Key (what to resolve) and a Target (where the value goes):

A plain string converts implicitly to a file-name criterion, so FileSplitCriteria.Add("tenant") keeps working as before.

Well-known keys 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 (each whitespace run replaced with a single _).

🛡️ Every segment is sanitized: characters invalid in file names (path separators included) become _, and . / .. become _, so a logged value can never write outside RootFolderPath.

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");

Folder criteria move values from the file name into subfolders:

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

    // one folder per day, one subfolder per tenant, one file per level
    options.FileSplitCriteria.Clear();
    options.FileSplitCriteria.Add(FileSplitCriterion.Folder(KnownFileSplitCriteria.LocalDate));
    options.FileSplitCriteria.Add(FileSplitCriterion.Folder("tenant"));
    options.FileSplitCriteria.Add(KnownFileSplitCriteria.LogLevel); // file name
});

/var/log/myapp/
└── 20260903/
    └── acme/
        ├── Information-log.txt
        └── Warning-log.txt

Missing subfolders are created on first write, and FileSizeLimit rolls files inside their own subfolder.

Plans for version next

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