jattac.libs.logger 1.0.1

Jattac Logging Library

The Jattac Logging Library is a simple yet powerful library designed to log exceptions in .NET applications. It provides built-in support for logging to the console and disk, while also allowing developers to extend it with custom log targets.

This guide will walk you through everything you need to know to use the library effectively, even if you're new to logging or .NET development.

Features

• Built-in Log Targets:
  • Console Logger: Logs error messages to the console.
  • Disk Logger: Logs error messages to disk files and automatically deletes files older than 30 days.
• Extensible: Add custom log targets by implementing a simple interface.
• Rich Exception Information: Captures detailed exception data for better debugging.
• Asynchronous Logging: All logging operations are asynchronous to avoid blocking your application.

Getting Started

Prerequisites

To use this library, you need:

• A .NET project targeting .NET Standard 2.0, .NET 6.0, or .NET Framework 4.8 (as supported by the library).
• Basic knowledge of C# programming.

Installation

The easiest way to use the library is by installing it via NuGet. Open your terminal or Package Manager Console and run the following command:

dotnet add package jattac.libs.logger

Alternatively, you can install it via the NuGet Package Manager in Visual Studio:

1. Right-click on your project in the Solution Explorer.
2. Select Manage NuGet Packages.
3. Search for jattac.libs.logger.
4. Click Install.

For more details, visit the NuGet package page.

Usage

Setting Up the Logger

The library uses an ErrorLogger class to manage logging. You need to create an instance of ErrorLogger and specify the log targets (e.g., console, disk, or custom targets).

Here’s how to set up a global static logger in your application:

using jattac.libs.logger;
using jattac.libs.logger.LogTargets;

public partial class Program
{
    public static ErrorLogger ErrorLogger = new ErrorLogger(new HashSet<IErrorLogTarget>
    {
        new ConsoleErrorTarget(), // Logs to the console
        new DiskErrorLogTarget()  // Logs to disk
    });

    public static void Main(string[] args)
    {
        // Your application logic here
    }
}

Logging Errors

Once the logger is set up, you can use it to log exceptions anywhere in your code. For example:

public void MyMethod()
{
    try
    {
        // Code that might throw an exception
    }
    catch (Exception ex)
    {
        // Log the exception with a custom message
        Program.ErrorLogger.Log(ex, "An error occurred in MyMethod");
    }
}

Rich Exception Information

The library uses a RichException class to capture detailed information about exceptions, including stack traces and custom descriptors. This ensures that logs provide meaningful insights for debugging.

Built-in Log Targets

1. Console Logger

The ConsoleErrorTarget logs error messages to the console in red text. It resets the console color after logging.

Example:

new ConsoleErrorTarget();

2. Disk Logger

The DiskErrorLogTarget logs error messages to disk files. It automatically deletes files older than 30 days to manage disk space.

Customizing the Disk Logger

You can specify a custom log directory and retention period when creating a DiskErrorLogTarget:

new DiskErrorLogTarget(customLogDirectory: "C:\\Logs", retentionPeriod: TimeSpan.FromDays(60));

Extending the Library

If you need to log to additional targets (e.g., a database, cloud service, or third-party logging system), you can create a custom log target by implementing the IErrorLogTarget interface.

Implementing a Custom Log Target

The IErrorLogTarget interface requires a single asynchronous method, LogAsync, which receives a RichException object.

Here’s an example of a custom log target that writes logs to a database:

using jattac.libs.logger;
using jattac.libs.logger.Data;

public class DatabaseErrorLogTarget : IErrorLogTarget
{
    public async Task LogAsync(RichException richException)
    {
        // Custom logic to log the exception to a database
        await Task.Run(() =>
        {
            Console.WriteLine($"Logging to database: {richException}");
        });
    }
}

Adding the Custom Target to the Logger

After creating your custom log target, include it in the ErrorLogger during instantiation:

public partial class Program
{
    public static ErrorLogger ErrorLogger = new ErrorLogger(new HashSet<IErrorLogTarget>
    {
        new ConsoleErrorTarget(),
        new DiskErrorLogTarget(),
        new DatabaseErrorLogTarget() // Custom log target
    });
}

Advanced Topics

Handling Log Target Failures

If a log target fails (e.g., due to a file system error or database connection issue), the library ensures that the failure does not affect the original exception or other log targets. For example, the ConsoleErrorTarget catches and logs any errors that occur during logging.

Managing Disk Space

The DiskErrorLogTarget automatically deletes log files older than the specified retention period (default: 30 days). You can customize this behavior by specifying a different retention period during instantiation.

Contributing

Contributions are welcome! If you have ideas for improving the library or adding new features, feel free to:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Submit a pull request with a detailed description of your changes.

License

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

Example Project

Here’s a complete example of using the library in a console application:

using System;
using System.Collections.Generic;
using jattac.libs.logger;
using jattac.libs.logger.LogTargets;

public class Program
{
    public static ErrorLogger ErrorLogger = new ErrorLogger(new HashSet<IErrorLogTarget>
    {
        new ConsoleErrorTarget(),
        new DiskErrorLogTarget()
    });

    public static void Main(string[] args)
    {
        try
        {
            // Simulate an error
            throw new InvalidOperationException("This is a test exception");
        }
        catch (Exception ex)
        {
            ErrorLogger.Log(ex, "An error occurred in the Main method");
        }
    }
}

This guide should help you get started with the Jattac Logging Library and make the most of its features. Happy logging!