ZLogger Documentation

ZLogger is a zero-allocation text and structured logger for .NET and Unity. It is built on top of Microsoft.Extensions.Logging, allowing it to integrate seamlessly with frameworks like ASP.NET Core and Generic Host while eliminating the overhead typically associated with bridging different logging systems.

Key features include:

• High Performance: Leverages C# 10 String Interpolation and .NET 8's IUtf8SpanFormattable to output directly in UTF8, avoiding the costs of UTF16-to-UTF8 encoding and value boxing.
• Structured Logging: Integrates with System.Text.Json's Utf8JsonWriter for efficient structured log output.
• Cloud-Native Optimized: Designed for high-performance console output suitable for cloud log management.
• Compatibility: Delivers peak performance on .NET 8+, but maintains consistent performance on .NET 6 and .NET Standard 2.0 via a custom fallback implementation.
• Standard Features: Supports LogLevel configuration from JSON, category filtering, and logging scopes.

To create a custom logging destination, implement the ILogger interface. The Log<TState> method is the core where you define how messages are processed (e.g., writing to a specific console, a database, or a custom file format). You can use IsEnabled(LogLevel) to filter logs before processing them to improve performance.

using Microsoft.Extensions.Logging;

public sealed class ColorConsoleLogger : ILogger
{
    private readonly string _name;
    private readonly Func<ColorConsoleLoggerConfiguration> _getCurrentConfig;

    public ColorConsoleLogger(
        string name,
        Func<ColorConsoleLoggerConfiguration> getCurrentConfig) =>
        (_name, _getCurrentConfig) = (name, getCurrentConfig);

    public IDisposable? BeginScope<TState>(TState state) where TState : notnull => default!;

    public bool IsEnabled(LogLevel logLevel) =>
        _getCurrentConfig().LogLevelToColorMap.ContainsKey(logLevel);

    public void Log<TState>(
        LogLevel logLevel,
        EventId eventId,
        TState state,
        Exception? exception,
        Func<TState, Exception?, string> formatter)
    {
        if (!IsEnabled(logLevel))
        {
            return;
        }

        ColorConsoleLoggerConfiguration config = _getCurrentConfig();
        if (config.EventId == 0 || config.EventId == eventId.Id)
        {
            ConsoleColor originalColor = Console.ForegroundColor;

            Console.ForegroundColor = config.LogLevelToColorMap[logLevel];
            Console.WriteLine($"[{eventId.Id,2}: {logLevel,-12}]");

            Console.ForegroundColor = originalColor;
            Console.Write($"     {_name} - ");

            Console.ForegroundColor = config.LogLevelToColorMap[logLevel];
            Console.Write($"{formatter(state, exception)}");

            Console.ForegroundColor = originalColor;
            Console.WriteLine();
        }
    }
}

The Microsoft.Bcl.AsyncInterfaces package provides the necessary definitions for asynchronous stream types (IAsyncEnumerable<T>, IAsyncEnumerator<T>, and IAsyncDisposable<T>) on older platforms like .NET Framework and .NET Standard 2.0. This enables the use of C# async iterators (using await foreach and yield return) which were introduced in C# 8.0.

Note: This library is not necessary or recommended if you are targeting .NET Core 3.0+ or .NET Standard 2.1+, as these versions include these types natively.

using System;
using System.Collections.Generic;
using System.Threading.Tasks;

internal static class Program
{
    private static async Task Main()
    {
        Console.WriteLine("Starting...");
        await foreach (var value in GetValuesAsync())
        {
            Console.WriteLine(value);
        }
        Console.WriteLine("Finished!");

        static async IAsyncEnumerable<int> GetValuesAsync()
        {
            for (int i = 0; i < 10; i++)
            {
                await Task.Delay(TimeSpan.FromSeconds(1));
                yield return i;
            }
        }
    }
}

The UseJsonFormatter method allows you to modify the JSON structure. Key customization options include:

• IncludeProperties: A bitmask to select which properties to include (e.g., Timestamp | LogLevel | Message | ParameterKeyValues).
• JsonPropertyNames: Allows renaming standard keys (e.g., renaming LogLevel to severity).
• PropertyKeyValuesObjectName: Defines the name of the nested object for payload key-values.
• AdditionalFormatter: A callback to add arbitrary JSON objects or fields (e.g., for cloud provider labels).

// Example: Customizing for Google Cloud Logging
public static ZLoggerOptions UseCloudLoggingJsonFormat(this ZLoggerOptions options)
{
    return options.UseJsonFormatter(formatter =>
    {
        formatter.IncludeProperties = Timestamp | LogLevel | Message | ParameterKeyValues;

        formatter.JsonPropertyNames = JsonPropertyNames.Default with
        {
            LogLevel = Encode("severity"),
            LogLevelNone = Encode("DEFAULT"),
            LogLevelTrace = Encode("DEBUG"),
            LogLevelDebug = Encode("DEBUG"),
            LogLevelInformation = Encode("INFO"),
            LogLevelWarning = Encode("WARNING"),
            LogLevelError = Encode("ERROR"),
            LogLevelCritical = Encode("CRITICAL"),
            Message = Encode("message"),
            Timestamp = Encode("timestamp"),
        };

        formatter.PropertyKeyValuesObjectName = Encode("jsonPayload");

        var labels = Encode("logging.googleapis.com/labels");
        var category = Encode("category");
        var eventId = Encode("eventId");
        var userId = Encode("userId");

        formatter.AdditionalFormatter = (Utf8JsonWriter writer, in LogInfo logInfo) =>
        {
            writer.WriteStartObject(labels);
            writer.WriteString(category, logInfo.Category.JsonEncoded);
            writer.WriteString(eventId, logInfo.EventId.Name);

            if (logInfo.ScopeState != null && !logInfo.ScopeState.IsEmpty)
            {
                foreach (var item in logInfo.ScopeState.Properties)
                {
                    if (item.Key == "userId")
                    {
                        writer.WriteString(userId, item.Value!.ToString());
                        break;
                    }
                }
            }
            writer.WriteEndObject();
        };
    });
}