Shaunebu.Common.Logging 1.0.1

Shaunebu.Common.Logging 📝🚀

Overview ✨

Shaunebu.Common.Logging is a lightweight, extensible logging library for modern .NET applications targeting .NET 9 and .NET 10. It provides a custom Shaunebu.Common.Logging.Abstractions.ILogger abstraction, structured message templates, scopes, lazy message factories, queue-based processing, deterministic flushing, file rotation, diagnostics, redaction, and console/file providers.

The primary API is the custom ILogger interface. Standard Microsoft.Extensions.Logging abstractions can also be enabled with the additive AddShaunebuMicrosoftLogging adapter, which feeds the same queue, provider, scope, redaction, flush, and disposal pipeline.

For complete runnable examples, see Shaunebu.Common.Logging.Client.

Feature Comparison 🆚

Installation 📦

dotnet add package Shaunebu.Common.Logging

Quick Start 🚀

1. Basic Setup

using Microsoft.Extensions.DependencyInjection;
using Shaunebu.Common.Logging.Abstractions;
using Shaunebu.Common.Logging.Enums;
using Shaunebu.Common.Logging.Extensions;

var services = new ServiceCollection();

services
    .AddShaunebuLogging(options =>
    {
        options.MinimumLevel = LogLevel.Information;
        options.ApplicationName = "MyApp";
        options.Environment = "Development";
        options.IncludeScopes = true;
        options.BatchSize = 50;
        options.BatchInterval = TimeSpan.FromSeconds(2);
    })
    .AddConsole()
    .AddFile(options =>
    {
        options.FilePath = "logs/application.log";
        options.MaxFileSizeBytes = 5 * 1024 * 1024;
        options.MaxFileCount = 5;
    });

using var serviceProvider = services.BuildServiceProvider();
var logger = serviceProvider.GetRequiredService<ILogger>();

logger.LogInformation("Application started");

2. Basic Usage

public sealed class OrderService
{
    private readonly ILogger _logger;

    public OrderService(ILogger logger)
    {
        _logger = logger;
    }

    public void ProcessOrder(Order order)
    {
        _logger.LogInformation("Processing order {OrderId}", order.Id);

        try
        {
            Process(order);
            _logger.LogInformation("Order {OrderId} processed successfully", order.Id);
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Failed to process order {OrderId}", order.Id);
        }
    }
}

Core Features 🎯

1. Structured Logging 🏷️

logger.LogInformation(
    "User {UserName} with ID {UserId} purchased {ItemCount} items for {Total}",
    "JohnDoe",
    12345,
    3,
    99.99m);

logger.LogError(exception, "Order {OrderId} failed for customer {CustomerId}", orderId, customerId);

Message-template placeholders are rendered into the message and captured as properties by name. If more values are supplied than placeholders, only matched placeholders become properties. If fewer values are supplied, unmatched placeholders remain in the rendered message.

2. Lazy Evaluation ⚡

logger.LogDebug(() =>
{
    var expensiveData = CalculateExpensiveMetrics();
    return $"Performance metrics: {expensiveData}";
});

Lazy factories are only evaluated when the configured level and provider filters can accept the entry.

3. Scoped Logging 🔄

using (logger.BeginScope(new Dictionary<string, object>
{
    ["OrderId"] = order.Id,
    ["CustomerId"] = order.CustomerId,
    ["TotalAmount"] = order.Total
}))
{
    logger.LogInformation("Starting order processing");
    logger.LogDebug("Processing order items");
    logger.LogInformation("Order processing completed");
}

When IncludeScopes is true, scope properties are copied into each accepted entry. Global context is added first, outer scopes then inner scopes override it, explicit log properties override scopes, and explicit LogEntry context fields such as UserId, SessionId, and CorrelationId have final precedence.

4. Multiple Providers 🎪

services
    .AddShaunebuLogging(options =>
    {
        options.MinimumLevel = LogLevel.Debug;
        options.IncludeScopes = true;
    })
    .AddConsole(options =>
    {
        options.MinimumLevel = LogLevel.Debug;
        options.IncludeCategory = true;
        options.IncludeProperties = true;
        options.TimestampFormat = "HH:mm:ss.fff";
    })
    .AddFile(options =>
    {
        options.FilePath = "logs/app.log";
        options.AllowedRootDirectory = AppContext.BaseDirectory;
        options.RejectSymbolicLinks = true;
        options.MaxFileSizeBytes = 10 * 1024 * 1024;
        options.MaxFileCount = 10;
        options.IncludeExceptionStacktrace = true;
    });

5. Queue Policies 🚦

services.AddShaunebuLogging(options =>
{
    options.QueueCapacity = 10_000;
    options.QueueFullPolicy = QueueFullPolicy.DropNewest;
    options.QueueAdmissionTimeout = TimeSpan.FromMilliseconds(100);
});

QueueCapacity = null preserves the original unbounded queue behavior. A positive capacity enables the configured QueueFullPolicy: Wait, DropNewest, DropOldest, or Reject.

6. Redaction 🔒

services.AddShaunebuLogging(options =>
{
    options.Redaction.Enabled = true;
    options.Redaction.ReplacementText = "[redacted]";
    options.Redaction.PropertyNames.Add("Password");
    options.Redaction.PropertyNames.Add("Authorization");
    options.Redaction.PropertyNames.Add("AccessToken");
});

Redaction is opt-in and property-name based. It applies before provider rendering to configured structured properties, scope properties, Microsoft logging state, context fields, rendered template values, and supported exception data.

Advanced Usage 🛠️

Configuration-Based Setup ⚙️

{
  "Logging": {
    "MinimumLevel": "Information",
    "ApplicationName": "MyApp",
    "Environment": "Production",
    "IncludeScopes": true,
    "BatchSize": 100,
    "BatchInterval": "00:00:05",
    "QueueCapacity": 10000,
    "QueueFullPolicy": "DropNewest",
    "LevelOverrides": {
      "Microsoft": "Warning",
      "System": "Error",
      "MyApp.Business": "Debug"
    }
  }
}

services.AddShaunebuLogging(configuration.GetSection("Logging"));

Microsoft.Extensions.Logging Integration 🔌

services
    .AddShaunebuLogging(options =>
    {
        options.MinimumLevel = LogLevel.Information;
        options.IncludeScopes = true;
    })
    .AddShaunebuMicrosoftLogging()
    .AddConsole();

This registers Microsoft.Extensions.Logging.ILogger, ILogger<T>, and ILoggerFactory adapters backed by the same LoggingService. Disposing the Microsoft adapter does not dispose the shared service.

Custom Logging Providers 🧩

public sealed class CustomLoggingProvider : ILoggingProvider
{
    public string Name => "Custom";

    public Task WriteAsync(LogEntry entry)
    {
        return SendToExternalService(entry);
    }

    public bool IsEnabled(LogLevel level)
    {
        return level >= LogLevel.Information;
    }

    public Task FlushAsync()
    {
        return Task.CompletedTask;
    }

    public void Dispose()
    {
    }
}

Diagnostics Snapshot 🩺

var loggingService = serviceProvider.GetRequiredService<LoggingService>();
var diagnostics = loggingService.GetDiagnosticsSnapshot();

Console.WriteLine($"Accepted: {diagnostics.AcceptedEntries}");
Console.WriteLine($"Processed: {diagnostics.ProcessedEntries}");
Console.WriteLine($"Dropped: {diagnostics.DroppedEntries}");
Console.WriteLine($"Rejected: {diagnostics.RejectedEntries}");
Console.WriteLine($"Provider failures: {diagnostics.ProviderFailures}");

Diagnostics snapshots are immutable and do not expose mutable counters or raw provider exception object graphs.

Lifecycle and Flushing 🔄

LoggingService accepts entries until disposed. FlushAsync waits for all entries accepted before the flush boundary to be processed, then flushes providers. Dispose stops accepting new entries, drains accepted entries, flushes providers, and then disposes providers.

var loggingService = serviceProvider.GetRequiredService<LoggingService>();

logger.LogInformation("Before shutdown");
await loggingService.FlushAsync(TimeSpan.FromSeconds(10));
loggingService.Dispose();

Log calls after disposal are ignored.

Performance Tips 🚀

1. Use lazy evaluation for expensive log message generation.
2. Set provider minimum levels so disabled entries skip formatting and rendering work.
3. Choose queue policies intentionally for high-volume applications.
4. Use scopes for contextual data instead of repeating properties manually.
5. Flush during shutdown when the application owns the logging lifetime.

Performance Comparison

Best Practices 📝

✅ DO

logger.LogInformation("User {UserId} completed action {ActionType}", userId, actionType);

logger.LogDebug(() => $"Computed value: {ExpensiveCalculation()}");

using (logger.BeginScope(new Dictionary<string, object>
{
    ["CorrelationId"] = correlationId,
    ["TenantId"] = tenantId
}))
{
    logger.LogInformation("Processing request");
}

options.LevelOverrides["Microsoft.EntityFrameworkCore"] = LogLevel.Warning;

❌ DON'T

logger.LogDebug("User " + userId + " did " + action); // Avoid string concatenation

logger.LogError("Something failed"); // Include the exception when one exists

logger.LogInformation("User password: {Password}", password); // Configure redaction first

API Reference 📚

ILogger Interface

LoggingService

Configuration Options

Examples 🎨

API Controller Logging

[ApiController]
[Route("api/[controller]")]
public sealed class UsersController : ControllerBase
{
    private readonly Microsoft.Extensions.Logging.ILogger<UsersController> _logger;

    public UsersController(Microsoft.Extensions.Logging.ILogger<UsersController> logger)
    {
        _logger = logger;
    }

    [HttpGet("{id}")]
    public async Task<ActionResult<User>> GetUser(int id)
    {
        using (_logger.BeginScope(new Dictionary<string, object>
        {
            ["Action"] = "GetUser",
            ["UserId"] = id,
            ["RequestId"] = HttpContext.TraceIdentifier
        }))
        {
            _logger.LogInformation("Getting user {UserId}", id);

            var user = await _userService.GetUserAsync(id);
            if (user is null)
            {
                _logger.LogWarning("User {UserId} not found", id);
                return NotFound();
            }

            return user;
        }
    }
}

Background Service Logging

public sealed class BackgroundWorkerService : BackgroundService
{
    private readonly Microsoft.Extensions.Logging.ILogger<BackgroundWorkerService> _logger;

    public BackgroundWorkerService(Microsoft.Extensions.Logging.ILogger<BackgroundWorkerService> logger)
    {
        _logger = logger;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        _logger.LogInformation("Background worker started");

        while (!stoppingToken.IsCancellationRequested)
        {
            try
            {
                _logger.LogDebug("Starting work iteration");
                await DoWorkAsync(stoppingToken);
                _logger.LogDebug("Work iteration completed");
            }
            catch (Exception ex) when (ex is not OperationCanceledException)
            {
                _logger.LogError(ex, "Error in background work iteration");
            }

            await Task.Delay(TimeSpan.FromMinutes(1), stoppingToken);
        }
    }
}

Security Behavior 🔐

Line-oriented providers escape control characters in rendered text as \uXXXX, including carriage returns, line feeds, tabs, and other control characters. This keeps one logical log entry from creating forged extra physical lines.

Property rendering is resilient. If a property value cannot be serialized because it is cyclic, too deep, or has throwing members, the provider writes deterministic fallback text such as:

<serialization-failed: Namespace.TypeName>

Redaction is disabled by default. When enabled, configured property names are matched with ordinal case-insensitive comparison. Matching structured properties, scope properties, Microsoft logging state, and LogEntry context properties are replaced before provider rendering. Rendered message values originating from redacted structured properties are replaced with the configured replacement text. Exception data values are not mutated on the original exception; rendered exception text is redacted where configured data keys match.

Troubleshooting 🔧

Logs not appearing?

• Check MinimumLevel and provider-specific minimum levels.
• Verify dependency injection setup.
• Call FlushAsync before reading file output in short-lived apps.
• Check GetDiagnosticsSnapshot() for dropped, rejected, or provider-failure counts.

Missing scoped properties?

• Ensure IncludeScopes = true.
• Use a using statement around BeginScope.
• Remember that explicit log properties override scope properties with the same key.

File path rejected?

• Check AllowedRootDirectory.
• Use paths that remain inside the allowed root after canonicalization.
• Disable RejectSymbolicLinks only when your deployment explicitly accepts that risk.

Limitations ⚠️

• Redaction is property-name based and opt-in; it does not perform automatic PII detection.
• Queue bounding is opt-in; the default remains unbounded for compatibility.
• File allowed-root validation is opt-in; existing consumers without a root keep existing path behavior.
• Provider APIs do not include batch write or cancellation-token methods.
• Public option and model classes remain mutable for compatibility, but runtime services snapshot configuration and caller-owned dictionaries.

Roadmap 🗺️

See docs/Roadmap.md for planned features, version buckets, and acceptance gates.

Target Frameworks 🎯

• net9.0
• net10.0

Version Compatibility 📌

Current compatibility policy keeps existing public API signatures, target frameworks, and package versioning behavior while adding optional integration, queue, redaction, file-security, diagnostics, and snapshot features.

License 📄

This package declares the MIT license in NuGet metadata.