Oakrey.Log.Abstractions 3.0.0

Oakrey.Log.Abstractions

1. Overview

The "Log.Abstractions" project provides shared contracts and infrastructure for Oakrey logging packages. It contains logger interfaces, log levels, log entry models, logger factory/proxy support, optional secret sanitizer contracts, and common logging utilities used by Oakrey.Log and related platform packages.

2. Features

Logging Contracts:

• ILogger: Defines the common application logging API for Trace, Debug, Information, Warning, Error, and Critical messages.
• ILogger<T>: Provides a typed logger contract for module-specific logging.
• ILoggerEngine: Defines the low-level sink contract used by logger implementations.

Logging Levels:

• Supports standard logging levels: Trace, Debug, Information, Warning, Error, and Critical (Level enum).
• Provides short string, display name, and parsing helpers for log levels.

Logger Management:

• LoggerFactory: Manages logger instances, global thresholds, module-specific filters, and optional secret sanitization.
• LoggerProxy: Provides module-specific logger instances backed by the shared logger factory.

Secret Sanitization Contracts:

• ILogSecretSanitizer: Allows plugging in a sanitizer that can redact log entries before they reach logger sinks.
• EmptyLogSecretSanitizer: Default no-op sanitizer used to avoid overhead in applications that do not need secret redaction.
• SecretSanitizationResult: Represents sanitizer output and redaction metadata.
• Concrete sanitizers are provided by the optional Oakrey.Log.Sanitizers package.

Log Entry Representation:

• LogEntry: Represents a single log entry with level, module, message, arguments, formatted message, and timestamp.

Utilities:

• LoggerHelper: Provides safe message formatting and level helper methods.
• LoggerExtensions: Provides convenience methods for entering, leaving, and safely executing logged actions.
• ExceptionsHandling: Flattens nested exception messages for better readability.

Extensibility:

• LoggerBase: Abstract base class for custom logger implementations.
• Concrete loggers are provided by Oakrey.Log, Oakrey.Log.Windows, and related packages.

3. Installation

You can install the package via NuGet Package Manager, Package Manager Console or the .NET CLI.

NuGet Package Manager

1. Open your project in Visual Studio.
2. Navigate to Tools > NuGet Package Manager > Manage NuGet Packages for Solution....
3. Search for Oakrey.Log.Abstractions and click Install.

.NET CLI

Run the following command in your terminal:

dotnet add package Oakrey.Log.Abstractions

Package Manager Console

Run the following command in your Package Manager Console:

Install-Package Oakrey.Log.Abstractions

4. Usage

Secret sanitization is disabled by default through EmptyLogSecretSanitizer, so logging stays lightweight unless an application explicitly configures a real sanitizer.

LoggerFactory.UseEmptySecretSanitizer();

Applications that need secret redaction can reference Oakrey.Log.Sanitizers and configure a concrete sanitizer:

LoggerFactory.SetSecretSanitizer(new DefaultSecretSanitizer());

When a configured sanitizer redacts a value, LoggerFactory emits a warning entry with metadata about the event. The warning does not include the original secret value.

5. Requirements

• .NET 10 or higher

6. Project Information

• Author: Oakrey
• Company: Oakrey (Website Link)
• License: MIT
• Repository: Git Repository
• Project URL: Project Website

7. Contributing

Contributions are welcome! Feel free to open issues or submit pull requests to improve the package.

8. License

This project is licensed under the MIT License. See the LICENSE file for details.