G4.Abstraction.Logging.md

G4.Abstraction.Logging

G4.Abstraction.Logging is a flexible, structured logging library designed to simplify logging across applications. It supports various log formats and allows custom handling through events, providing detailed control over log entry creation and management. This logger can be configured via settings and is compatible with Microsoft.Extensions.Logging.

Installation

To install G4.Abstraction.Logging, add the NuGet package:

dotnet add package G4.Abstraction.Logging

Features

• Structured Logging: Outputs log entries in JSON, Simple, and Text formats for easy readability.
• Event-Driven: Allows subscribing to log creation and error events.
• Customizable Configurations: Supports configuration through G4LoggerSettings.
• Trace Listener Support: Can be configured to write logs to specific trace listeners.
• Platform Limitations: Not supported in browser environments.

Usage

1. Basic Setup

Create a G4Logger instance by specifying the logger name and configuration settings. Here’s a simple example:

using G4.Abstraction.Logging;

var logger = new G4Logger("G4.Api", () => new G4LoggerSettings
{
    G4Logger = new G4LoggerConfiguration
    {
        OutputDirectory = "./logs",
        Type = "JSON"
    },
    LogLevel = new Dictionary<string, LogLevel>
    {
        ["Default"] = LogLevel.Information
    }
});

logger.Log(LogLevel.Information, new EventId(1, "Startup"), "Application started.", null, (s, e) => s);

2. Basic Logging Methods

G4Logger supports basic logging methods for different log levels, such as LogInformation, LogWarning, LogError, etc.

// Log an informational message
logger.LogInformation("This is an informational message.");

// Log a warning
logger.LogWarning("This is a warning message.");

// Log an error with an exception
var exception = new InvalidOperationException("An error occurred.");
logger.LogError(exception, "An error message with exception details.");

// Log a critical error
logger.LogCritical("Critical error encountered during operation.");

// Log debug information
logger.LogDebug("Debug information for troubleshooting.");

Each of these methods logs a message at the specified log level, and you can pass an optional exception for detailed error logging.

3. Configuring Log Format and Output Directory

You can specify the log format (JSON, Simple, or Text) and output directory in G4LoggerSettings:

var settings = new G4LoggerSettings
{
    G4Logger = new G4LoggerConfiguration
    {
        OutputDirectory = "./logs",
        Type = "JSON" // Supports "JSON", "Simple", and "Text"
    }
};

4. Event Subscription

G4Logger provides several events for customized handling of log entries. You can subscribe to these events to modify log entries before they’re written or handle errors during logging.

logger.LogCreating += (sender, logEntry) => 
{
    logEntry["AdditionalInfo"] = "Custom data before log creation.";
};

logger.LogCreated += (sender, logEntry) =>
{
    Console.WriteLine("Log created successfully.");
};

logger.LogError += (sender, exception) =>
{
    Console.WriteLine($"Error occurred during logging: {exception.Message}");
};

Example Configuration in appsettings.json

You can configure G4Logger settings in appsettings.json for flexible, environment-based configuration.

{
  "Logging": {
    "G4Logger": {
      "OutputDirectory": "./logs",
      "Type": "JSON",
      "EventId": 0
    },
    "LogLevel": {
      "Default": "Information",
      "G4.Api": "Debug"
    },
    "AddDebug": true,
    "AddConsole": true
  }
}

Work in Progress

• Log File Size Limitation and Rotation: Future versions will add support for limiting the size of log files and implementing log file rotation. This will allow G4Logger to automatically archive or remove older logs once they exceed a specified file size, ensuring efficient log management.

License

This library is released under the Apache License 2.0.