EonaCat.LogStack flow-based logging library for .NET, designed for zero-allocation logging paths and superior memory efficiency. It features a rich fluent API for routing log events to dozens of destinations — from console and file to Slack, Discord, Redis, Elasticsearch, and beyond.

Features

Flow-based architecture — route log events to one or many output destinations simultaneously
Booster system — enrich every log event with contextual metadata (machine name, process ID, thread info, memory, uptime, correlation IDs, and more)
Pre-build modifiers — intercept and mutate log events before they are written
Zero-allocation hot path — AggressiveInlining throughout, StringBuilder pooling, and ref-based builder pattern
Async-first — all flows implement IAsyncDisposable and FlushAsync
Resilience built-in — retry, failover, throttling, and rolling buffer flows
Tamper-evident audit trail — SHA-256 hash-chained audit files
Encrypted file logging — AES-encrypted log files with a built-in decrypt utility
Compression — GZip-compressed rolled log files
Category routing — split logs into separate files per category or log level
Diagnostics — live counters (total logged, total dropped, per-flow stats)

Supported Targets

.NET Standard 2.1
.NET 8.0
.NET Framework 4.8

Installation

dotnet add package EonaCat.LogStack

Quick Start

await using var logger = LogBuilder.CreateDefault("MyApp");

logger.Information("Application started");
logger.Warning("Low memory warning");
logger.Error(ex, "Unexpected error occurred");

CreateDefault creates a logger writing to both the console and a ./logs directory, enriched with machine name and process ID.

Fluent Configuration

Build a fully customised logger using LogBuilder:

await using var logger = new LogBuilder("MyApp")
    .WithMinimumLevel(LogLevel.Debug)
    .WithTimestampMode(TimestampMode.Utc)
    .WriteToConsole(useColors: true)
    .WriteToFile("./logs", filePrefix: "app", maxFileSize: 50 * 1024 * 1024)
    .WriteToSlack("https://hooks.slack.com/services/...")
    .BoostWithMachineName()
    .BoostWithProcessId()
    .BoostWithCorrelationId()
    .Build();

Logging Methods

logger.Trace("Verbose trace message");
logger.Debug("Debug detail");
logger.Information("Something happened");
logger.Warning("Potential problem");
logger.Warning(ex, "Warning with exception");
logger.Error("Something failed");
logger.Error(ex, "Error with exception");
logger.Critical("System is going down");
logger.Critical(ex, "Critical failure");

// With structured properties
logger.Log(LogLevel.Information, "User logged in",
    ("UserId", 42),
    ("IP", "192.168.1.1"));

Available Flows

Flows can be extended with custom implementations of `IFlow`, but here are the built-in options:

Flow	Method	Description
Console	`WriteToConsole()`	Colored console output
File	`WriteToFile()`	Batched, rotated, compressed file output
Encrypted File	`WriteToEncryptedFile()`	AES-encrypted log files
Memory	`WriteToMemory()`	In-memory ring buffer
Audit	`WriteToAudit()`	Tamper-evident hash-chained audit trail
Database	`WriteToDatabase()`	ADO.NET database sink
HTTP	`WriteToHttp()`	Generic HTTP endpoint (batched)
Webhook	`WriteToWebhook()`	Generic webhook POST
Email	`WriteToEmail()`	HTML digest emails via SMTP
Slack	`WriteToSlack()`	Slack incoming webhooks
Discord	`WriteToDiscord()`	Discord webhooks
Microsoft Teams	`WriteToMicrosoftTeams()`	Teams incoming webhooks
Telegram	`WriteToTelegram()`	Telegram bot messages
SignalR	`WriteToSignalR()`	Real-time SignalR hub push
Redis	`RedisFlow()`	Redis Pub/Sub + optional List persistence
Elasticsearch	`WriteToElasticSearch()`	Elasticsearch index
Splunk	`WriteToSplunkFlow()`	Splunk HEC
Graylog	`WriteToGraylogFlow()`	GELF over UDP or TCP
Syslog UDP	`WriteToSyslogUdp()`	RFC-5424 Syslog over UDP
Syslog TCP	`WriteToSyslogTcp()`	RFC-5424 Syslog over TCP (with optional TLS)
TCP	`WriteToTcp()`	Raw TCP (with optional TLS)
UDP	`WriteToUdp()`	Raw UDP datagrams
SNMP Trap	`WriteToSnmpTrap()`	SNMP v2c traps
Zabbix	`WriteToZabbixFlow()`	Zabbix trapper protocol
EventLog	`WriteToEventLogFlow()`	Remote event log forwarding
Rolling Buffer	`WriteToRollingBuffer()`	Circular buffer with trigger-based flush
Throttled	`WriteToThrottled()`	Token-bucket rate limiting + deduplication
Retry	`WriteToRetry()`	Automatic retry with exponential back-off
Failover	`WriteToFailover()`	Primary/secondary failover
Diagnostics	`WriteDiagnostics()`	Periodic diagnostic snapshots
Status	`WriteToStatusFlow()`	Service health monitoring

Available Boosters

Boosters enrich every log event with additional properties before it reaches any flow.

new LogBuilder("MyApp")
    .BoostWithMachineName()       // host name
    .BoostWithProcessId()         // PID
    .BoostWithThreadId()          // managed thread ID
    .BoostWithThreadName()        // thread name
    .BoostWithUser()              // current OS user
    .BoostWithApp()               // app name and base directory
    .BoostWithApplication("MyApp", "2.0.0")  // explicit name + version
    .BoostWithEnvironment("Production")
    .BoostWithOS()                // OS description
    .BoostWithFramework()         // .NET runtime description
    .BoostWithMemory()            // working set in MB
    .BoostWithUptime()            // process uptime in seconds
    .BoostWithProcStart()         // process start time
    .BoostWithDate()              // current date (yyyy-MM-dd)
    .BoostWithTime()              // current time (HH:mm:ss.fff)
    .BoostWithTicks()             // current timestamp ticks
    .BoostWithCorrelationId()     // Activity.Current correlation ID
    .BoostWithCustomText("env", "prod")   // arbitrary key/value
    .Boost("myBooster", () => new Dictionary<string, object?> { ["key"] = "val" })
    ...

Pre-Build Modifiers

Modifiers run after boosters and can mutate or cancel a log event before it is dispatched to flows:

logger.AddModifier((ref LogEventBuilder builder) =>
{
    builder.WithProperty("RequestId", Guid.NewGuid().ToString());
});

Resilience Patterns

Retry with exponential back-off

.WriteToRetry(
    primaryFlow: new HttpFlow("https://logs.example.com"),
    maxRetries: 5,
    initialDelay: TimeSpan.FromMilliseconds(200),
    exponentialBackoff: true)

Primary / secondary failover

.WriteToFailover(
    primaryFlow: new ElasticSearchFlow("https://es-prod:9200"),
    secondaryFlow: new FileFlow("./fallback-logs"))

Token-bucket throttling with deduplication

.WriteToThrottled(
    inner: new SlackFlow(webhookUrl),
    burstCapacity: 10,
    refillPerSecond: 1.0,
    deduplicate: true,
    dedupWindow: TimeSpan.FromSeconds(60))

Rolling buffer — flush context on error

.WriteToRollingBuffer(
    capacity: 500,
    triggerLevel: LogLevel.Error,
    triggerTarget: new FileFlow("./error-context"))

Encrypted File Logging

.WriteToEncryptedFile("./secure-logs", password: "s3cr3t")

To decrypt later:

LogBuilder.DecryptFile(
    encryptedPath: "./secure-logs/log.enc",
    outputPath:    "./secure-logs/log.txt",
    password:      "s3cr3t");

Audit Trail

The audit flow produces a tamper-evident file where every entry is SHA-256 hash-chained. Deleting or modifying any past entry invalidates all subsequent hashes.

.WriteToAudit(
    directory: "./audit",
    auditLevel: AuditLevel.WarningAndAbove,
    includeProperties: true)

Verify integrity at any time:

bool intact = AuditFlow.Verify("./audit/audit.audit");

Log Message Template

Both ConsoleFlow and FileFlow accept a customisable template string:

[{ts}] [{tz}] [Host: {host}] [Category: {category}] [Thread: {thread}] [{logtype}] {message}{props}

Token	Description
`{ts}`	Timestamp (yyyy-MM-dd HH:mm:ss.fff)
`{tz}`	Timezone (UTC or local name)
`{host}`	Machine name
`{category}`	Logger category
`{thread}`	Managed thread ID
`{pid}`	Process ID
`{logtype}`	Log level label (INFO, WARN, ERROR, …)
`{message}`	Log message text
`{props}`	Structured properties as key=value pairs
`{newline}`	Line break

Diagnostics

var diag = logger.GetDiagnostics();
Console.WriteLine($"Logged: {diag.TotalLogged}, Dropped: {diag.TotalDropped}");

Flushing and Disposal

// Flush all pending events
await logger.FlushAsync();

// Dispose (flushes automatically)
await logger.DisposeAsync();

Events

logger.OnLog += (sender, msg) =>
{
    // Fired for every log event that passes filters
    Console.WriteLine($"[Event] {msg.Level}: {msg.Message}");
};

Custom Flows

Implement IFlow (or extend FlowBase) to create your own destination:

public class MyFlow : FlowBase
{
    public MyFlow() : base("MyFlow", LogLevel.Trace) { }

    public override Task<WriteResult> BlastAsync(LogEvent logEvent, CancellationToken ct = default)
    {
        // Write logEvent somewhere
        return Task.FromResult(WriteResult.Success);
    }

    public override Task FlushAsync(CancellationToken ct = default) => Task.CompletedTask;
}

// Register with:
new LogBuilder("App").WriteTo(new MyFlow()).Build();

README.md

EonaCat.LogStack