Novutils.Logging.Serilog 1.0.33

Novautils.Logging

Novautils.Logging is a lightweight and structured logging library for .NET applications, built on top of Serilog. It simplifies the process of configuring logging, providing essential features like console, file, and Loki logging out of the box. This library is designed to set a basic but effective logging configuration, particularly with Loki, where a minimal, controlled set of labels is standardized for easier filtering and analysis of logs.

Features

• Console Logging: Customizable console logging with themes and structured message formats.
• File Logging: Log messages to files with support for rotation and retention policies.
• Grafana Loki Integration: Streamlined logging to Loki, with a predefined set of labels for consistent log organization and filtering.
• Minimal Configuration: Designed to be easy to configure, using a structured approach for typical logging needs.
• Error Handling: Provides FatalLoggingException for critical logging errors, allowing graceful application failure handling.

Objective

The primary goal of Novautils.Logging is to offer a straightforward and structured way to configure logging for .NET applications. The library focuses on providing a streamlined configuration with a special emphasis on Loki logging, establishing a minimum set of required labels for filtering logs effectively. These labels are controlled and normalized to ensure consistency across different environments and services.

Installation

To include Novautils.Logging in your project, clone the repository and include the Novutils.Logging project in your solution.

Alternatively, if available on NuGet:

dotnet add package Novutils.Logging

Serilog Dependencies

Novutils.Logging is built on top of several Serilog packages, ensuring comprehensive logging support:

• Serilog: Core logging functionality.
• Serilog.Expressions: Allows expression-based log message formatting.
• Serilog.Extensions.Logging: Provides integration with .NET logging infrastructure.
• Serilog.Settings.Configuration: Supports configuration using settings files such as appsettings.json.
• Serilog.Sinks.Console: Enables logging to the console.
• Serilog.Sinks.File: Enables file-based logging.
• Serilog.Sinks.Grafana.Loki: Enables logging to Grafana Loki, with predefined labels.

Usage

1. Basic Setup

You can configure logging using the LoggingSettings class, either via appsettings.json or programmatically.

2. Configuring the Logger Sinks

Console Logging

The ConsoleLoggerSettings class allows you to control console logging, including themes and log message formats.

• Theme: Supported values are "Grayscale", "Literate", and "Code".
• LogLevel: Defines the minimum log level (e.g., Information, Warning, Error).
• LogMsgFormat: Uses Serilog Expressions for structured log messages.

Example configuration for the console logger:

"ConsoleLogger": {
  "LogEnabled": true,
  "LogLevel": "Information",
  "LogMsgFormat": "{@t:yyyy-MM-dd HH:mm:ss.fff} [{@l:u4}] [{SourceContext}] {@m:lj}\n{@x}",
  "Theme": "Code"
}

File Logging

The FileLoggerSettings class lets you log messages to files, with options for file size limits, log file naming, and retention.

• LogFolder: Directory where log files are stored.
• LogFileName: The name of the log file. Defaults to the application name if not specified.
• LogFileMaxBytes: Maximum size (in bytes) before a new log file is created.
• LogFileBackupCount: Number of backup log files to retain.

Example configuration for file logging:

"FileLogger": {
  "LogEnabled": true,
  "LogLevel": "Warning",
  "LogFileName": "app.log",
  "LogFolder": "Logs",
  "LogFileMaxBytes": 10485760, // 10 MB
  "LogFileBackupCount": 5
}

Loki Logging

The LokiLoggerSettings class enables logging to Grafana Loki, with a structured, minimal set of standardized labels for effective log filtering. These labels include:

• host: Hostname or IP address where the logs are generated.
• application: The application name, derived from the AppName setting.
• environment: The environment in which the application is running (e.g., development, production).
• service: (Optional) The application service name, if provided.

These labels are designed to help filter logs based on the most common and required data points, with some labels normalized under controlled values for consistency.

Example configuration for Loki:

"LokiLogger": {
  "LogEnabled": true,
  "LogLevel": "Error",
  "LokiBaseUrl": "http://loki.example.com",
  "LokiTenant": "",
  "LokiCustomHostLabel": "",
  "LokiUsername": "your-username",
  "LokiPassword": "your-password"
}

3. Full Example Configuration (appsettings.json)

Here's a full example using all three logging sinks:

{
  "Logging": {
    "AppName": "MyApp",
    "AppEnvironment": "Development",
    "AppService": "MyService",
    "ConsoleLogger": {
      "LogEnabled": true,
      "LogLevel": "Information",
      "LogMsgFormat": "{@t:yyyy-MM-dd HH:mm:ss.fff} [{@l:u4}] [{SourceContext}] {@m:lj}\n{@x}",
      "Theme": "Code"
    },
    "FileLogger": {
      "LogEnabled": true,
      "LogLevel": "Warning",
      "LogFileName": "myapp.log",
      "LogFolder": "Logs",
      "LogFileMaxBytes": 10485760,
      "LogFileBackupCount": 5
    },
    "LokiLogger": {
      "LogEnabled": true,
      "LogLevel": "Error",
      "LokiBaseUrl": "http://loki.example.com",
      "LokiTenant": "",
      "LokiCustomHostLabel": "",
      "LokiUsername": "your-username",
      "LokiPassword": "your-password"
    }
  }
}

4. Dependency Injection Integration

Novautils.Logging integrates seamlessly with the .NET Dependency Injection system via LoggerConfigurator. This ensures logging is correctly configured for the entire application lifecycle.

Example in Program.cs:

public static IHostBuilder CreateHostBuilder(string[] args) =>
    Host.CreateDefaultBuilder(args)
        .ConfigureAppConfiguration((context, config) =>
        {
            config.AddJsonFile("appsettings.json", optional: false, reloadOnChange: true);
        })
        .ConfigureServices((context, services) =>
        {
            var loggingSettings = new LoggingSettings();
            context.Configuration.GetSection("Logging").Bind(loggingSettings);

            var loggerConfiguration = new LoggerConfiguration();
            LoggerConfigurator.SetupLogging(loggerConfiguration, loggingSettings);

            Log.Logger = loggerConfiguration.CreateLogger();

            services.AddLogging(loggingBuilder =>
            {
                loggingBuilder.ClearProviders();
                loggingBuilder.AddSerilog(Log.Logger, dispose: true);
            });
        });

5. Error Handling and Fatal Logging

In the event of a critical logging failure, such as an inability to initialize logging sinks, Novutils.Logging throws a FatalLoggingException. This ensures that applications can handle these critical issues gracefully and appropriately.

Example:

try
{
    LoggerConfigurator.SetupLogging(loggerConfiguration, loggingSettings);
}
catch (FatalLoggingException ex)
{
    Console.WriteLine($"Critical logging error: {ex.Message}");
    Environment.Exit(1);
}

Running Tests

To ensure reliability, Novutils.Logging includes comprehensive unit tests. Run the tests using the following command:

dotnet test tests/Novutils.Logging.Serilog.UnitTests

Usage Example

A sample project is included under Novutils.Logging.Serilog.UsageExample, which demonstrates a real-world usage of logging with configuration from appsettings.json. It includes:

• Configuring logging for console, file, and Loki sinks.
• Sample log messages at different levels.
• Structured logging and error handling.

Note on Testing with Grafana Loki

For users who wish to test the logging capabilities of Novautils.Logging.Serilog in a complete Grafana Loki environment, we recommend utilizing our companion project: Log Monitor Stack. This project provides a fully dockerized setup to deploy a Grafana Loki stack locally, allowing you to monitor and visualize your application logs with ease.

By following the instructions in the Log Monitor Stack repository, you can quickly spin up a testing environment that includes Grafana, Loki, and Promtail, giving you real-time insights into your application's logging performance and behavior.

This setup is ideal for local testing, debugging, and validating the integration between your Serilog configuration and Grafana Loki, ensuring a seamless logging experience.

For more information, please visit the Log Monitor Stack repository.

Contributing

Contributions are always welcome! Follow these steps to contribute:

1. Fork the repository.
2. Create a new branch (git checkout -b feature-branch).
3. Make your changes and ensure all tests pass.
4. Commit your changes (git commit -am 'Add feature').
5. Push to the branch (git push origin feature-branch).
6. Open a Pull Request.

License

Novutils.Logging is licensed under the MIT License. See the LICENSE file for more information.