# 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

```bash
dotnet add package EonaCat.LogStack
```

---

## Quick Start

```csharp
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`:

```csharp
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

```csharp
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.

```csharp
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:

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

---

## Resilience Patterns

### Retry with exponential back-off
```csharp
.WriteToRetry(
    primaryFlow: new HttpFlow("https://logs.example.com"),
    maxRetries: 5,
    initialDelay: TimeSpan.FromMilliseconds(200),
    exponentialBackoff: true)
```

### Primary / secondary failover
```csharp
.WriteToFailover(
    primaryFlow: new ElasticSearchFlow("https://es-prod:9200"),
    secondaryFlow: new FileFlow("./fallback-logs"))
```

### Token-bucket throttling with deduplication
```csharp
.WriteToThrottled(
    inner: new SlackFlow(webhookUrl),
    burstCapacity: 10,
    refillPerSecond: 1.0,
    deduplicate: true,
    dedupWindow: TimeSpan.FromSeconds(60))
```

### Rolling buffer — flush context on error
```csharp
.WriteToRollingBuffer(
    capacity: 500,
    triggerLevel: LogLevel.Error,
    triggerTarget: new FileFlow("./error-context"))
```

---

## Encrypted File Logging

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

To decrypt later:
```csharp
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.

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

Verify integrity at any time:
```csharp
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

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

---

## Flushing and Disposal

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

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

---

## Events

```csharp
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:

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