Add customizable archive naming for FileLogWriter (Fixes #2)

Author: xoofx

site/docs/file-writer.md

@@ -55,6 +55,40 @@ Behavior:
 - Retention deletes oldest archives beyond `RetainedFileCountLimit`.
 - `FlushToDisk = true` forces durable `FileStream.Flush(true)` for crash-critical workloads.
 
+## Custom archive file names
+
+You can customize rolling archive names with `FileLogWriterOptions.ArchiveFileNameFormatter`.
+
+```csharp
+var writer = new FileLogWriter(
+    new FileLogWriterOptions("logs/output.txt")
+    {
+        RollingInterval = FileRollingInterval.Daily,
+        ArchiveFileNameFormatter = FileArchiveFileNameFormatters.DateTime
+    });
+```
+
+This produces names like `output.2026-02-19-19_16_03.txt`.
+
+Built-in helpers:
+
+- `FileArchiveFileNameFormatters.Compact` (default behavior)
+- `FileArchiveFileNameFormatters.DateTime`
+- `FileArchiveFileNameFormatters.DateTimeWithMilliseconds`
+
+You can also provide your own callback:
+
+```csharp
+ArchiveFileNameFormatter = context =>
+    $"{context.BaseFileName}.{context.Timestamp:yyyy-MM-dd-HH_mm_ss}{context.Extension}";
+```
+
+Guidelines:
+
+- Return a file **name**, not a path.
+- Keep names in the same directory as the active file.
+- Include `context.Sequence` (or allow suffixing) to avoid collisions in multi-process scenarios.
+
 ## JSON-lines logging
 
 ```csharp

src/XenoAtom.Logging.Tests/FileLogWriterTests.cs

@@ -299,6 +299,92 @@ public void FileLogWriter_ArchiveTimestampMode_UsesConfiguredClock()
         Assert.IsTrue(localArchive.Contains(localStamp, StringComparison.Ordinal));
     }
 
+    [TestMethod]
+    public void FileLogWriter_ArchiveFileNameFormatter_CanUseReadableDateTimeFormat()
+    {
+        var fixedUtcTime = new DateTimeOffset(2026, 02, 09, 19, 16, 3, TimeSpan.Zero);
+        var expectedArchiveFileName = "output.2026-02-09-19_16_03.txt";
+        var filePath = Path.Combine(_tempDirectory, "output.txt");
+
+        var writer = new FileLogWriter(
+            new FileLogWriterOptions(filePath)
+            {
+                AutoFlush = true,
+                FileSizeLimitBytes = 1,
+                ArchiveFileNameFormatter = FileArchiveFileNameFormatters.DateTime
+            });
+
+        var config = CreateConfig(writer);
+        config.TimeProvider = new MutableTimeProvider(fixedUtcTime);
+
+        LogManager.Initialize(config);
+        var logger = LogManager.GetLogger("Tests.File.Archive.Format");
+        logger.Info("first");
+        logger.Info("second");
+        LogManager.Shutdown();
+
+        var archives = Directory.GetFiles(_tempDirectory, "output.*.txt", SearchOption.TopDirectoryOnly)
+            .Select(Path.GetFileName)
+            .ToArray();
+        CollectionAssert.Contains(archives, expectedArchiveFileName);
+    }
+
+    [TestMethod]
+    public void FileLogWriter_ArchiveFileNameFormatter_IgnoresSequence_StillProducesUniqueArchiveName()
+    {
+        var fixedUtcTime = new DateTimeOffset(2026, 02, 09, 19, 16, 3, TimeSpan.Zero);
+        var filePath = Path.Combine(_tempDirectory, "output.txt");
+        var collidingArchivePath = Path.Combine(_tempDirectory, "output.2026-02-09-19_16_03.txt");
+
+        File.WriteAllText(collidingArchivePath, "collision");
+
+        var writer = new FileLogWriter(
+            new FileLogWriterOptions(filePath)
+            {
+                AutoFlush = true,
+                FileSizeLimitBytes = 1,
+                ArchiveFileNameFormatter = static context => $"{context.BaseFileName}.{context.Timestamp.ToString("yyyy-MM-dd-HH_mm_ss", CultureInfo.InvariantCulture)}{context.Extension}"
+            });
+
+        var config = CreateConfig(writer);
+        config.TimeProvider = new MutableTimeProvider(fixedUtcTime);
+
+        LogManager.Initialize(config);
+        var logger = LogManager.GetLogger("Tests.File.Archive.Format.SequenceFallback");
+        logger.Info("first");
+        logger.Info("second");
+        LogManager.Shutdown();
+
+        Assert.IsTrue(File.Exists(collidingArchivePath), "The pre-existing archive should remain untouched.");
+
+        var generatedArchives = Directory.GetFiles(_tempDirectory, "output.*.txt", SearchOption.TopDirectoryOnly)
+            .Select(Path.GetFileName)
+            .ToArray();
+        Assert.IsTrue(generatedArchives.Any(name => string.Equals(name, "output.2026-02-09-19_16_03.1.txt", StringComparison.Ordinal)));
+    }
+
+    [TestMethod]
+    public void FileLogWriter_ArchiveFileNameFormatter_InvalidPath_Throws()
+    {
+        var filePath = Path.Combine(_tempDirectory, "output.txt");
+        var writer = new FileLogWriter(
+            new FileLogWriterOptions(filePath)
+            {
+                AutoFlush = true,
+                FileSizeLimitBytes = 1,
+                ArchiveFileNameFormatter = static _ => "nested/output.txt"
+            });
+
+        LogManager.Initialize(CreateConfig(writer));
+        var logger = LogManager.GetLogger("Tests.File.Archive.InvalidFormatter");
+        logger.Info("first");
+
+        var exception = Assert.Throws<InvalidOperationException>(() => logger.Info("second"));
+        Assert.IsNotNull(exception);
+        StringAssert.Contains(exception.Message, "must return a file name, not a path");
+        LogManager.Shutdown();
+    }
+
     [TestMethod]
     public void FileLogWriter_FlushToDisk_UsesDurableFlushMode()
     {

src/XenoAtom.Logging/Writers/FileArchiveFileNameContext.cs

@@ -0,0 +1,18 @@
+// Copyright (c) Alexandre Mutel. All rights reserved.
+// Licensed under the BSD-Clause 2 license.
+// See license.txt file in the project root for full license information.
+
+namespace XenoAtom.Logging.Writers;
+
+/// <summary>
+/// Context passed to <see cref="FileLogWriterOptions.ArchiveFileNameFormatter"/> when rolling files.
+/// </summary>
+/// <param name="BaseFileName">The base file name without extension (for example <c>app</c>).</param>
+/// <param name="Extension">The active file extension (for example <c>.log</c>).</param>
+/// <param name="Timestamp">The roll timestamp converted according to <see cref="FileLogWriterOptions.ArchiveTimestampMode"/>.</param>
+/// <param name="Sequence">The sequence suffix used to disambiguate name collisions. The first attempt uses <c>0</c>.</param>
+public readonly record struct FileArchiveFileNameContext(
+    string BaseFileName,
+    string Extension,
+    DateTime Timestamp,
+    long Sequence);

src/XenoAtom.Logging/Writers/FileArchiveFileNameFormatters.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Alexandre Mutel. All rights reserved.
+// Licensed under the BSD-Clause 2 license.
+// See license.txt file in the project root for full license information.
+
+using System.Globalization;
+
+namespace XenoAtom.Logging.Writers;
+
+/// <summary>
+/// Built-in helpers for <see cref="FileLogWriterOptions.ArchiveFileNameFormatter"/>.
+/// </summary>
+public static class FileArchiveFileNameFormatters
+{
+    /// <summary>
+    /// Produces the default compact file name format:
+    /// <c>&lt;base&gt;.&lt;yyyyMMddHHmmssfff&gt;[.&lt;sequence&gt;]&lt;extension&gt;</c>.
+    /// </summary>
+    /// <param name="context">The archive naming context.</param>
+    /// <returns>The archive file name.</returns>
+    public static string Compact(FileArchiveFileNameContext context)
+        => Format(context, "yyyyMMddHHmmssfff");
+
+    /// <summary>
+    /// Produces a human-readable file name format:
+    /// <c>&lt;base&gt;.&lt;yyyy-MM-dd-HH_mm_ss&gt;[.&lt;sequence&gt;]&lt;extension&gt;</c>.
+    /// </summary>
+    /// <param name="context">The archive naming context.</param>
+    /// <returns>The archive file name.</returns>
+    public static string DateTime(FileArchiveFileNameContext context)
+        => Format(context, "yyyy-MM-dd-HH_mm_ss");
+
+    /// <summary>
+    /// Produces a human-readable file name format with milliseconds:
+    /// <c>&lt;base&gt;.&lt;yyyy-MM-dd-HH_mm_ss_fff&gt;[.&lt;sequence&gt;]&lt;extension&gt;</c>.
+    /// </summary>
+    /// <param name="context">The archive naming context.</param>
+    /// <returns>The archive file name.</returns>
+    public static string DateTimeWithMilliseconds(FileArchiveFileNameContext context)
+        => Format(context, "yyyy-MM-dd-HH_mm_ss_fff");
+
+    private static string Format(in FileArchiveFileNameContext context, string timestampFormat)
+    {
+        var stamp = context.Timestamp.ToString(timestampFormat, CultureInfo.InvariantCulture);
+        if (context.Sequence == 0)
+        {
+            return $"{context.BaseFileName}.{stamp}{context.Extension}";
+        }
+
+        return $"{context.BaseFileName}.{stamp}.{context.Sequence.ToString(CultureInfo.InvariantCulture)}{context.Extension}";
+    }
+}

src/XenoAtom.Logging/Writers/FileLogWriter.cs

@@ -34,6 +34,7 @@ public class FileLogWriter : LogWriter
     private readonly FileOptions _fileOptions;
     private readonly bool _flushToDisk;
     private readonly FileArchiveTimestampMode _archiveTimestampMode;
+    private readonly Func<FileArchiveFileNameContext, string>? _archiveFileNameFormatter;
     private readonly FileLogWriterFailureMode _failureMode;
     private readonly Action<FileLogWriterFailureContext>? _failureHandler;
     private readonly int _retryCount;
@@ -112,6 +113,7 @@ public FileLogWriter(FileLogWriterOptions options)
         _fileOptions = options.FileOptions;
         _flushToDisk = options.FlushToDisk;
         _archiveTimestampMode = options.ArchiveTimestampMode;
+        _archiveFileNameFormatter = options.ArchiveFileNameFormatter;
         _failureMode = options.FailureMode;
         _failureHandler = options.FailureHandler;
         _retryCount = options.RetryCount;
@@ -389,11 +391,22 @@ private bool TryMoveCurrentFileToArchive(DateTime timestamp)
             _ => throw new ArgumentOutOfRangeException(nameof(_archiveTimestampMode), _archiveTimestampMode, null)
         };
 
-        var stamp = archiveTimestamp.ToString("yyyyMMddHHmmssfff", CultureInfo.InvariantCulture);
         var sequence = 0L;
+        var attemptedFileNames = new HashSet<string>(StringComparer.Ordinal);
         while (true)
         {
-            var archivePath = GetArchivePath(stamp, sequence);
+            var archiveFileName = GetArchiveFileName(archiveTimestamp, sequence);
+            if (!attemptedFileNames.Add(archiveFileName))
+            {
+                archiveFileName = AppendSequenceSuffix(archiveFileName, sequence);
+                if (!attemptedFileNames.Add(archiveFileName))
+                {
+                    sequence++;
+                    continue;
+                }
+            }
+
+            var archivePath = Path.Combine(_directoryPath, archiveFileName);
             try
             {
                 File.Move(_filePath, archivePath, overwrite: false);
@@ -412,12 +425,35 @@ private bool TryMoveCurrentFileToArchive(DateTime timestamp)
         }
     }
 
-    private string GetArchivePath(string stamp, long sequence)
+    private string GetArchiveFileName(DateTime archiveTimestamp, long sequence)
+    {
+        var context = new FileArchiveFileNameContext(_archiveFileNamePrefix, _archiveFileExtension, archiveTimestamp, sequence);
+        var formatter = _archiveFileNameFormatter;
+        var archiveFileName = formatter is null
+            ? FileArchiveFileNameFormatters.Compact(context)
+            : formatter(context);
+
+        if (string.IsNullOrWhiteSpace(archiveFileName))
+        {
+            throw new InvalidOperationException("ArchiveFileNameFormatter returned null, empty, or whitespace.");
+        }
+
+        if (!string.Equals(Path.GetFileName(archiveFileName), archiveFileName, StringComparison.Ordinal))
+        {
+            throw new InvalidOperationException("ArchiveFileNameFormatter must return a file name, not a path.");
+        }
+
+        return archiveFileName;
+    }
+
+    private static string AppendSequenceSuffix(string archiveFileName, long sequence)
     {
-        var suffix = sequence == 0
-            ? stamp
-            : $"{stamp}.{sequence.ToString(CultureInfo.InvariantCulture)}";
-        return Path.Combine(_directoryPath, $"{_archiveFileNamePrefix}.{suffix}{_archiveFileExtension}");
+        var extension = Path.GetExtension(archiveFileName);
+        var extensionLength = extension.Length;
+        var baseFileName = extensionLength == 0
+            ? archiveFileName
+            : archiveFileName.Substring(0, archiveFileName.Length - extensionLength);
+        return $"{baseFileName}.{sequence.ToString(CultureInfo.InvariantCulture)}{extension}";
     }
 
     private void ApplyRetentionPolicy()

src/XenoAtom.Logging/Writers/FileLogWriterOptions.cs

@@ -57,6 +57,7 @@ public FileLogWriterOptions(FileLogWriterOptions options)
         FileOptions = options.FileOptions;
         FlushToDisk = options.FlushToDisk;
         ArchiveTimestampMode = options.ArchiveTimestampMode;
+        ArchiveFileNameFormatter = options.ArchiveFileNameFormatter;
         FailureMode = options.FailureMode;
         FailureHandler = options.FailureHandler;
         RetryCount = options.RetryCount;
@@ -138,6 +139,15 @@ public FileLogWriterOptions(FileLogWriterOptions options)
     /// </summary>
     public FileArchiveTimestampMode ArchiveTimestampMode { get; set; } = FileArchiveTimestampMode.Utc;
 
+    /// <summary>
+    /// Gets or sets an optional callback used to build archive file names when rolling.
+    /// </summary>
+    /// <remarks>
+    /// When <see langword="null"/>, the default archive naming format is used:
+    /// <c>&lt;base&gt;.&lt;yyyyMMddHHmmssfff&gt;[.&lt;sequence&gt;]&lt;extension&gt;</c>.
+    /// </remarks>
+    public Func<FileArchiveFileNameContext, string>? ArchiveFileNameFormatter { get; set; }
+
     /// <summary>
     /// Gets or sets how write/roll I/O failures are handled.
     /// </summary>