XenoAtom.Logging 1.0.0

XenoAtom.Logging

<img align="right" width="256px" height="256px" src="https://raw.githubusercontent.com/XenoAtom/XenoAtom.Logging/main/img/XenoAtom.Logging.png">

XenoAtom.Logging is a high-performance structured logging runtime for .NET, designed for zero allocations on the hot path and predictable throughput in both sync and async modes. It includes a high-efficiency interpolated logging API, structured properties/scopes, source-generated formatters, and production-grade file/JSON sinks.

✨ Features

• Performance-first (zero allocations on the hot path):
  • Allocation-aware interpolated-string handlers (Trace/Debug/Info/Warn/Error/Fatal)
  • Formatting into Span<char> with pooled buffers and optional segment metadata
• Sync by default, async when you need it:
  • Default mode is synchronous
  • Optional asynchronous mode with bounded queue and overflow policy (Drop, DropAndNotify, Block, Allocate)
• Structured logging:
  • Per-message properties (LogProperties)
  • Scopes (BeginScope) captured as snapshots
• Template-driven text formatting (source generation):
  • LogFormatter base class with shared settings (LevelFormat, TimestampFormat)
  • Generated template formatters (e.g. StandardLogFormatter) and segment kinds for rich sinks
• Terminal integration without System.Console:
  • XenoAtom.Logging.Terminal uses XenoAtom.Terminal for markup-aware output
  • TerminalLogControlWriter targets XenoAtom.Terminal.UI.Controls.LogControl for fullscreen/log-viewer apps
  • Visual attachments: log calls can attach XenoAtom.Terminal.UI.Visual (tables, layouts, rich widgets)
  • Terminal docs: https://xenoatom.github.io/terminal
• Production file and JSON sinks:
  • Rolling + retention (FileLogWriter, JsonFileLogWriter)
  • Failure policies and durability options
• Operational support:
  • Async error callback via LogManagerConfig.AsyncErrorHandler
  • Runtime diagnostics via LogManager.GetDiagnostics() (DroppedMessages, ErrorCount)
  • NativeAOT and trimming oriented (IsAotCompatible, IsTrimmable)

And the integration with LogControl:

📐 Requirements (.NET 10 / C# 14)

XenoAtom.Logging targets net10.0 and requires the .NET 10 SDK (C# 14).

📦 Package layout

dotnet add package XenoAtom.Logging
dotnet add package XenoAtom.Logging.Terminal

• XenoAtom.Logging: core runtime, formatters, stream/file/JSON writers
• XenoAtom.Logging also ships the generators/analyzers in-package (analyzers/dotnet/cs)
• XenoAtom.Logging.Terminal: terminal sink using XenoAtom.Terminal and XenoAtom.Terminal.UI

🚀 Quick start

using XenoAtom.Logging;
using XenoAtom.Logging.Writers;

var config = new LogManagerConfig
{
    RootLogger =
    {
        MinimumLevel = LogLevel.Info,
        Writers =
        {
            new FileLogWriter(
                new FileLogWriterOptions("logs/app.log")
                {
                    FileSizeLimitBytes = 10 * 1024 * 1024,
                    RollingInterval = FileRollingInterval.Daily,
                    RetainedFileCountLimit = 7
                })
        }
    }
};

LogManager.Initialize(config); // sync processor by default

var logger = LogManager.GetLogger("Sample");
logger.Info($"Hello {42}");

LogManager.Shutdown();

Enable async processing:

config.AsyncErrorHandler = exception =>
{
    Console.Error.WriteLine($"[logging async error] {exception}");
};

LogManager.InitializeForAsync(config);

🖥️ Terminal markup and visuals

Markup payload logging (terminal sink):

logger.InfoMarkup("[green]ready[/]");
logger.ErrorMarkup($"[bold red]failed[/] id={requestId}");

Visual attachments via XenoAtom.Terminal.UI (rendered under the log line by TerminalLogWriter):

using XenoAtom.Terminal.UI;
using XenoAtom.Terminal.UI.Controls;

var table = new Table()
    .Headers("Step", "Status", "Duration")
    .AddRow("Initialize", "OK", "00:00.045")
    .AddRow("ProcessRequest", "FAILED", "00:00.003");

logger.Info(table, "Run summary");
logger.InfoMarkup(table, "[bold]Run summary (styled)[/]");

TerminalLogWriter and TerminalLogControlWriter both expose Styles and SegmentStyleResolver for per-segment and per-level styling.

🧵 Thread safety

• LogManager and Logger are safe for concurrent logging.
• Configure LogManagerConfig, LoggerConfig.Writers, and writer filter collections from a single thread, then call ApplyChanges() when done.
• LogProperties is a mutable value type; avoid copying populated instances and dispose only the owner instance.
• In sync mode, writer exceptions propagate to callers; in async mode, use AsyncErrorHandler + diagnostics to observe failures.

See the thread-safety documentation at https://xenoatom.github.io/logging/docs/thread-safety/.

📖 Documentation

Full documentation is available at https://xenoatom.github.io/logging/docs.

🪪 License

This software is released under the BSD-2-Clause license.

🤗 Author

Alexandre Mutel aka xoofx.