Class LoggerExtensions

Extends ILogger with additional handy logging methods. We recommend that users standardize on calling these logger extensions as opposed to using Microsoft's standard Microsoft.Extensions.Logging.LoggerExtensions.

Inheritance

object

LoggerExtensions

Namespace: Neon.Diagnostics

Assembly: Neon.Common.dll

Syntax

public static class LoggerExtensions

Remarks

EVENT LOGGING:

This class extends ILogger with methods intended to be somewhat easier to use than Microsoft's extensions. Our logging method names end with "Ex" and we provide methods for logging critical, error, warning, information, debug and trace events. We have overrides for each log level that can be used for different purposes. We'll discuss the information methods below. The methods for the other log levels folow the same pattern.

The first thing to note, is that all logging methods include an optional attributeSetter parameter. This can be set to an Action that adds arbitrary tags to the event when logged. This is an easy and clean way to specify attributes, much cleaner than specifying a message format string as required by the Microsoft.Extensions.Logging.LoggerExtensions (e.g. there's no way to include an attribute without having it appear in the event message). Here's how this works:

logger.LogInformationEx("Test message",
    attributes => {
        attributes.Add("my-attr-0", "test-0");
        attributes.Add("my-attr-1", "test-1");
    });

note

The attributes lambda function is only called when the event is actually going to be logged, based on the current log level.

Some of our extensions accept the message as a string and others accept a lambda function that returns the message string. The general rule is that you should pass constant strings directly to the logging methods but strings generated at runtime via interpolation or other mechanisms should be specified by passing a message lambda function.

note

The message lambda function is only called when the event is actually going to be logged, based on the current log level.

The latter recomendation will improve performance because the lambda function won't be called when the event won't actually be logged due to the current log level, avoiding the overhead of generating the string. Imagine if your program logged a lot of TRACE events with dynamically generated messages. This means that when running at the INFORMATION log level, all of those trace messages would be created at runtime and then be immediately discarded, resulting in wasted CPU used to generate the message as well as extra heap allocations (all for nothing).

// Log a static message:
logger.LogInformationEx("Hello World!");
// Log a dynamic message:
var name = "Sally";
logger.LogInformation(() => $"Hello: {name}");
// YOU DON'T WANT TO DO THIS because the message string will always be generated at runtime,
// even when the event won't be logged due to the current log level:
logger.LogInformation($"Hello: {name}");

LogInformationEx(ILogger, string, Action<LogAttributes>): Used for logging a constant message string. Avoid calling this for dynamically generated messages.

LogInformationEx(ILogger, Func<string>, Action<LogAttributes>): Used for logging a dynamically generated message. This will be much more efficient when the event isn't going to be logged due to the current log level setting.

LogInformationEx(ILogger, Exception, string, Action<LogAttributes>): Used for logging an exception with a constant or null message. When message is passed as empty or null, a message generated from exception will be used.

LogInformationEx(ILogger, Exception, Func<string>, Action<LogAttributes>): Used for logging an exception with a dynamic message. When the message function is passed null, a message generated from exception will be used.

LOGGER ATTRIBUTES

Use the AddAttributes(ILogger, Action<LogAttributes>) method to create a new ILogger with new attributes such that these attributes will be included in subsequent events emitted by the logger. Note that attributes logged with the event will override logger attributes with the same name.

Here's how this works:

var logger     = TelemetryHub.CreateLogger("my-logger");
var attributes = new LogAttributes();
attributes.Add("my-attr-0", "test-0");
attributes.Add("my-attr-1", "test-1");
logger = logger.AddAttributes(attributes);  // Creates a new logger including the attributes passed.
logger.LogInformationEx("Test message");    // This event will include the new attributes
// This example overrides the logger's "test-1" attribute with the "OVERRIDE" value:
logger.LogInformationEx("Test message", attributes => attributes.Add("test-1", "OVERRIDE"));

note

IMPORTANT: Any additional attributes added to the logger returned will only be recognized by the neondSDK logger extensions LoggerExtensions with logging method names ending in "Ex", like: LogInformationEx(ILogger, Func<string>, Action<LogAttributes>). The standard Microsoft logger extension methods implemented by Microsoft.Extensions.Logging.LoggerExtensions will ignore these logger attributes.

Methods

AddAttributes(ILogger, Action<LogAttributes>)

This wraps the logger passed with another logger that adds a colection of attributes to every logged event.

note

IMPORTANT: Any additional attributes added to the logger returned will only be recognized by the neondSDK logger extensions LoggerExtensions with logging method names ending in "Ex", like: LogInformationEx(ILogger, Func<string>, Action<LogAttributes>). The standard Microsoft logger extension methods implemented by Microsoft.Extensions.Logging.LoggerExtensions will ignore these logger attributes.

Declaration

public static ILogger AddAttributes(this ILogger logger, Action<LogAttributes> attributeSetter)

Parameters

Type	Name	Description
ILogger	logger	The logger being wrapped.
Action<LogAttributes>	attributeSetter	Action used to add attributes to the logger.

Returns

Type	Description
ILogger	An ILogger that will include the attributes in every event it logs.

Remarks

This method returns a new logger that includes the attributes added by the attributeSetter action.

LogCriticalEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs a critical exception with a message returned by a custom message function.

Declaration

public static void LogCriticalEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	The exception.
Func<string>	messageFunc	Specifies the message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogCriticalEx(ILogger, Exception, string, Action<LogAttributes>)

Logs a critical exception.

Declaration

public static void LogCriticalEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies the exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogCriticalEx(ILogger, Func<string>, Action<LogAttributes>)

Logs a critical message retrieved via a message function.

Declaration

public static void LogCriticalEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	The message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogCriticalEx(ILogger, string, Action<LogAttributes>)

Logs a critical message.

Declaration

public static void LogCriticalEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies the message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogDebugEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs a debug exception with a message returned by a custom message function..

Declaration

public static void LogDebugEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogDebugEx(ILogger, Exception, string, Action<LogAttributes>)

Logs a debug exception.

Declaration

public static void LogDebugEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogDebugEx(ILogger, Func<string>, Action<LogAttributes>)

Logs a debug message retrieved via a message function.

Declaration

public static void LogDebugEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogDebugEx(ILogger, string, Action<LogAttributes>)

Logs a debug message.

Declaration

public static void LogDebugEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogErrorEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs an error exception with a message returned by a custom message function..

Declaration

public static void LogErrorEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogErrorEx(ILogger, Exception, string, Action<LogAttributes>)

Logs an error exception.

Declaration

public static void LogErrorEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogErrorEx(ILogger, Func<string>, Action<LogAttributes>)

Logs an error message retrieved via a message function.

Declaration

public static void LogErrorEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogErrorEx(ILogger, string, Action<LogAttributes>)

Logs an error message.

Declaration

public static void LogErrorEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogInformationEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs a information exception with a message returned by a custom message function..

Declaration

public static void LogInformationEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogInformationEx(ILogger, Exception, string, Action<LogAttributes>)

Logs an information exception.

Declaration

public static void LogInformationEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogInformationEx(ILogger, Func<string>, Action<LogAttributes>)

Logs an information message retrieved via a message function.

Declaration

public static void LogInformationEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogInformationEx(ILogger, string, Action<LogAttributes>)

Logs an information message.

Declaration

public static void LogInformationEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogTraceEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs a trace exception with a message returned by a custom message function..

Declaration

public static void LogTraceEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogTraceEx(ILogger, Exception, string, Action<LogAttributes>)

Logs a trace exception.

Declaration

public static void LogTraceEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogTraceEx(ILogger, Func<string>, Action<LogAttributes>)

Logs a trace message retrieved via a message function.

Declaration

public static void LogTraceEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogTraceEx(ILogger, string, Action<LogAttributes>)

Logs a trace message.

Declaration

public static void LogTraceEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogWarningEx(ILogger, Exception, Func<string>, Action<LogAttributes>)

Logs a warning exception with a message returned by a custom message function..

Declaration

public static void LogWarningEx(this ILogger logger, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogWarningEx(ILogger, Exception, string, Action<LogAttributes>)

Logs a warning exception.

Declaration

public static void LogWarningEx(this ILogger logger, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Exception	exception	Specifies exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogWarningEx(ILogger, Func<string>, Action<LogAttributes>)

Logs a warning message retrieved via a message function.

Declaration

public static void LogWarningEx(this ILogger logger, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
Func<string>	messageFunc	Specifies message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogWarningEx(ILogger, string, Action<LogAttributes>)

Logs a warning message.

Declaration

public static void LogWarningEx(this ILogger logger, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
string	message	Specifies message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogWithLevelEx(ILogger, LogLevel, Exception, Func<string>, Action<LogAttributes>)

Logs an exception with a message returned by a custom message function with the specified LogLevel.

Declaration

public static void LogWithLevelEx(this ILogger logger, LogLevel logLevel, Exception exception, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
LogLevel	logLevel	Specifies the LogLevel.
Exception	exception	The exception.
Func<string>	messageFunc	Specifies the message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogWithLevelEx(ILogger, LogLevel, Exception, string, Action<LogAttributes>)

Logs an exception retrieved via a message function with the specified LogLevel.

Declaration

public static void LogWithLevelEx(this ILogger logger, LogLevel logLevel, Exception exception, string message = null, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
LogLevel	logLevel	Specifies the LogLevel.
Exception	exception	Specifies the exception.
string	message	Optionally specifies the event message.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing attributes when the current log level prevents any log from being emitted, for better performance.

LogWithLevelEx(ILogger, LogLevel, Func<string>, Action<LogAttributes>)

Logs a message retrieved via a message function with the specified LogLevel.

Declaration

public static void LogWithLevelEx(this ILogger logger, LogLevel logLevel, Func<string> messageFunc, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
LogLevel	logLevel	Specifies the LogLevel.
Func<string>	messageFunc	The message function.
Action<LogAttributes>	attributeSetter	Optionally specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.

LogWithLevelEx(ILogger, LogLevel, string, Action<LogAttributes>)

Logs a message with the specified LogLevel.

Declaration

public static void LogWithLevelEx(this ILogger logger, LogLevel logLevel, string message, Action<LogAttributes> attributeSetter = null)

Parameters

Type	Name	Description
ILogger	logger	Specifies the logger.
LogLevel	logLevel	Specifies the LogLevel.
string	message	Specifies the message.
Action<LogAttributes>	attributeSetter	Specifies an action that can be used to add attributes to the event being logged.

Remarks

This method is intended mostly to avoid processing interpolated strings and attributes when the current log level prevents any log from being emitted, for better performance.