README.md

StructuredLoggerMessage

A library for high-performance structural logging, utilizing the .NET Extensions Logging Framework, and modeled after the .NET API for high-performance logging. The primary difference between the .NET LoggerMessage API, and the StructuralLoggerMessage API is that it allows for consumers to log data values for use by structural loggers, without requiring that those values be part of the format string used by text loggers.

Usage

The StructuralLoggerMessage API allows consumers to define specific log messages ahead-of-time, in the form of Action delegates that are type-safe and include cached calculation results for optimizing text generation of log messages.

public static readonly Action<ILogger, string, int, string?> DataValueChanged
    = StructuredLoggerMessage.Define<string, int, string?>(
        LogLevel.Debug,
        new EventId(1001, nameof(DataValueChanged)),
        "{DataValueName} Changed",
        "DataValue",
        "ChangedBy");

This allows a consumer to invoke...

DataValueChanged.Invoke(logger, "MyValue", 7, "me");

...to produce the text log message...

MyValue Changed

...and a structural log state consisting of...

{
    ["DataValueName"] => "MyValue",
    ["DataValue"] => 7,
    ["ChangedBy"] => "me"
    ["{OriginalFormat}"] => "{DataValueName} Changed"
}

This is equivalent to a call to the corresponding Microsoft API...

public static readonly Action<ILogger, string, int, string?> DataValueChanged
    = LoggerMessage.Define<string, int, string?>(
        LogLevel.Debug,
        new EventId(1001, nameof(DataValueChanged)),
        "{DataValueName} Changed: {DataValue} {ChangedBy}");

...except, as you can see, not all logged values must be embedded in the format string of the log message.