oddstech.common.unifiedlogging 1.0.2

OddsTech Common Unified Logging

A unified logging framework providing structured logging with correlation tracking, severity levels, and caller information. Standardizes logging across microservices with consistent format and automatic context enrichment.

Features

• Structured Logging Format: Consistent, parseable log format across all services
• Automatic Context Enrichment: Includes timestamp, log level, severity, assembly name, caller info
• Correlation ID Tracking: Automatic correlation ID extraction from HTTP context
• Severity Levels: LOW, MEDIUM, HIGH severity classification
• Caller Information: Automatic capture of source file and method name
• Additional Metadata: Support for custom key-value pairs
• Multi-Tenant Support: Site/tenant context in logs
• Exception Detail Extraction: Comprehensive exception logging with inner exceptions
• Zero Configuration: Works out-of-the-box with optional HTTP context configuration

Installation

dotnet add package oddstech.common.unifiedlogging

Quick Start

Basic Usage

using Microsoft.Extensions.Logging;
using oddstech.common.unifiedlogging.Extensions;
using oddstech.common.unifiedlogging.Enums;

public class MyService
{
    private readonly ILogger<MyService> _logger;

    public MyService(ILogger<MyService> logger)
    {
        _logger = logger;
    }

    public void DoWork()
    {
        // Information log with default LOW severity
        _logger.LogInformationUnified("Processing started");

        // Warning log with MEDIUM severity (default)
        _logger.LogWarningUnified("API response time exceeded threshold");

        // Error log with HIGH severity (default)
        _logger.LogErrorUnified("Database connection failed");
    }
}

Log Output Format

2025-11-24 17:06:00 - L:Information,S:LOW,P:MyApplication,T:MyService,M:DoWork,SITE:None - Processing started

With Custom Severity

_logger.LogInformationUnified(
    "Processing payment transaction",
    severity: LogSeverityEnum.HIGH
);

With Additional Metadata

var metadata = new[]
{
    new KeyValuePair<string, object>("UserId", userId),
    new KeyValuePair<string, object>("TransactionId", transactionId),
    new KeyValuePair<string, object>("Amount", amount)
};

_logger.LogInformationUnified(
    "Payment processed successfully",
    pairs: metadata
);

Output:

2025-11-24 17:06:00 - L:Information,S:LOW,P:MyApplication,T:PaymentService,M:ProcessPayment,SITE:None,UserId:12345,TransactionId:abc-123,Amount:100.50 - Payment processed successfully

With Site Context (Multi-Tenant)

_logger.LogInformationUnified(
    "User logged in",
    site: "MainSite"
);

Logging Exceptions

try
{
    // Some operation
}
catch (Exception ex)
{
    // Log exception with full details
    _logger.LogErrorUnified(ex);
    
    // Or with custom message
    _logger.LogErrorUnified("Failed to process payment", ex);
}

Configuration

Enable Correlation ID Tracking

Configure once during application startup to enable automatic correlation ID tracking:

using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;
using oddstech.common.unifiedlogging.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register HTTP context accessor
builder.Services.AddHttpContextAccessor();

var app = builder.Build();

// Configure unified logging with HTTP context accessor
var httpContextAccessor = app.Services.GetRequiredService<IHttpContextAccessor>();
LoggerExtensions.Configure(httpContextAccessor);

app.Run();

Once configured, correlation IDs will automatically be included in logs when available in the HTTP context items with key "CorrelationId".

API Reference

Extension Methods

LogInformationUnified

void LogInformationUnified(
    this ILogger logger,
    string message,
    LogSeverityEnum? severity = null,      // Defaults to LOW
    string site = "None",
    KeyValuePair<string, object>[]? pairs = null,
    [CallerFilePath] string callerFile = "",
    [CallerMemberName] string callerMethod = ""
)

LogWarningUnified

void LogWarningUnified(
    this ILogger logger,
    string message,
    LogSeverityEnum? severity = null,      // Defaults to MEDIUM
    string site = "None",
    KeyValuePair<string, object>[]? pairs = null,
    [CallerFilePath] string callerFile = "",
    [CallerMemberName] string callerMethod = ""
)

LogErrorUnified

// With message only
void LogErrorUnified(
    this ILogger logger,
    string message,
    LogSeverityEnum? severity = null,      // Defaults to HIGH
    string site = "None",
    KeyValuePair<string, object>[]? pairs = null,
    [CallerFilePath] string callerFile = "",
    [CallerMemberName] string callerMethod = ""
)

// With exception only
void LogErrorUnified(
    this ILogger logger,
    Exception ex,
    LogSeverityEnum? severity = null,
    string site = "None",
    KeyValuePair<string, object>[]? pairs = null,
    [CallerFilePath] string callerFile = "",
    [CallerMemberName] string callerMethod = ""
)

// With message and exception
void LogErrorUnified(
    this ILogger logger,
    string message,
    Exception ex,
    LogSeverityEnum? severity = null,
    string site = "None",
    KeyValuePair<string, object>[]? pairs = null,
    [CallerFilePath] string callerFile = "",
    [CallerMemberName] string callerMethod = ""
)

Severity Levels

public enum LogSeverityEnum
{
    LOW,      // Informational messages, normal operations
    MEDIUM,   // Warnings, potential issues
    HIGH      // Errors, critical issues requiring attention
}

Log Format Structure

Each log message follows this structure:

{Timestamp} - {Parameters} - {Message}

Parameters include:

• L: Log Level (Information, Warning, Error)
• S: Severity (LOW, MEDIUM, HIGH)
• P: Project/Assembly name
• T: Type/File name (caller)
• M: Method name (caller)
• SITE: Site/Tenant identifier
• CorrelationID: Request correlation ID (when available)
• Additional custom key-value pairs

Examples

Complete Example with All Features

public class OrderService
{
    private readonly ILogger<OrderService> _logger;

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

    public async Task<Order> ProcessOrder(int orderId, string site)
    {
        _logger.LogInformationUnified(
            "Order processing started",
            severity: LogSeverityEnum.LOW,
            site: site,
            pairs: new[]
            {
                new KeyValuePair<string, object>("OrderId", orderId)
            }
        );

        try
        {
            var order = await GetOrder(orderId);
            
            _logger.LogInformationUnified(
                "Order retrieved successfully",
                site: site,
                pairs: new[]
                {
                    new KeyValuePair<string, object>("OrderId", orderId),
                    new KeyValuePair<string, object>("OrderTotal", order.Total)
                }
            );

            return order;
        }
        catch (Exception ex)
        {
            _logger.LogErrorUnified(
                "Failed to process order",
                ex,
                severity: LogSeverityEnum.HIGH,
                site: site,
                pairs: new[]
                {
                    new KeyValuePair<string, object>("OrderId", orderId)
                }
            );
            throw;
        }
    }
}

Testing

The library includes comprehensive unit and BDD tests:

cd oddstech.common.unifiedlogging.tests
dotnet test

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or contributions, please visit the GitHub repository.