Modern structured logging extensions for .NET that separate human-readable messages from machine-readable attributes. Include contextual data (user IDs, correlation IDs, metrics) in logs without forcing them into message templates.
Modern, high-performance structured logging extensions for .NET that cleanly separate human-readable messages from machine-readable attributes. Stop cluttering your message templates with structured data and start writing logs that are easier to read and query.
Why Choose RandomSkunk.StructuredLogging?
Traditional structured logging forces you to embed data into message templates. This often leads to:
Verbose and Unreadable Messages: Log("User {UserId} logged in from {IPAddress}", userId, ipAddress)
Performance Overhead: Message template caching can consume memory and CPU.
Rigid Structure: You can only log what your template allows.
This library takes a different approach by treating messages and attributes as separate concerns, giving you the best of both worlds: clean, readable messages and rich, queryable data.
Features
✨ Clean Separation: Keep your log messages for humans and your attributes for machines.
🚀 High Performance: A design that avoids message template caching overhead.
📝 Powerful Interpolated Strings: Automatically extract attributes from interpolated strings ($"User {user.Name:<UserName>}") without sacrificing performance. The interpolation only happens if the log level is enabled!
💪 Flexible & Type-Safe: Pass attributes using tuples, dictionaries, or arrays with a rich set of overloads.
🎯 Multi-Targeted: Targets both .NET 8 and .NET 9.
Quick Start
1. Install the Package
dotnet add package RandomSkunk.StructuredLogging
2. Start Logging
Use the extension methods on Microsoft.Extensions.Logging.ILogger.
Basic Logging with Attributes
Pass attributes as a list of (string, object) tuples. The message remains clean and readable.
logger.Information("User logged in successfully",
("UserId", user.Id),
("SessionId", sessionId),
("LoginTime", DateTime.UtcNow));
For ultimate convenience, extract attributes directly from an interpolated string. The syntax {value:<AttributeName>} captures the value as an attribute and embeds it in the message.
This is not just a simple string.Format. The library uses a custom interpolated string handler that only evaluates the arguments and formats the string if the log level is enabled.
// The values for username and attemptCount are captured as attributes.
logger.Warning($"Failed login attempt for {username:<Username>}",
("AttemptCount", attemptCount),
("IPAddress", clientIp));
Performance is a core feature. This library is designed to minimize overhead in your application.
Conditional Evaluation
The custom interpolated string handlers are the magic behind the performance. String formatting and method calls inside an interpolated string only occur if the log level is enabled.
// If Debug logging is disabled, CalculateSize() is never called and no string is created.
logger.Debug($"Processing {items.Count:<ItemsCount>} items with total size {CalculateSize(items):<ItemsByteCount>N0} bytes");
No Message Caching
Unlike other libraries, we do not cache message templates. This eliminates memory overhead and performance penalties associated with managing a cache, making it ideal for dynamic log messages.
Advanced Usage
The library is flexible enough to handle any scenario.
Logging with Exceptions and Event IDs
All overloads support standard EventId and Exception arguments.
