👁 Image
EonaCat.LogStack.OpenTelemetryFlow 0.0.1

EonaCat.LogStack

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:

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}

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