logo
logo

Logging

The SDK comes with its own logging. This page describes its usage and how to extend it.

Logging messages

Logging can be accessed directly on the IMClient.

Writing a debug message:

MClient.Logger.Debug("A debug message.");

Writing an info message:

MClient.Logger.Info("An info message.");

Writing a warning message:

MClient.Logger.Warn("A warning message.");

Writing an error message:

MClient.Logger.Error("An error message.");

Logging levels

The minimum log level can be set on the MinimumLogLevel property.

There are four levels of logging defined:

  • Debug: used to log debugging information.
  • Info: used to log general information about the script's execution.
  • Warn: used to log warnings.
  • Error: log errors.

Minimum log level

The logging levels are ordered by priority (1 is the lowest priority):

  1. Debug
  2. Info
  3. Warn
  4. Error

Define the minimum log level as the level from which the script starts logging. A minimum log level excludes logs of a lower level. The following table describes the mapping between the selected logging level and the included logging levels.

Selected levelIncluded levels
Debug
  • Debug
  • Info
  • Warn
  • Error
Info
  • Info
  • Warn
  • Error
Warn
  • Warn
  • Error
Error
  • Error

The following four properties return true or false depending on the minimum log level:

  • IsDebugEnabled
  • IsInfoEnabled
  • IsWarnEnabled
  • IsErrorEnabled

Events

The ILogger interface exposes the OnLog event. Just before something is logged, the event will be fired. Note that the event is not fired when something was logged below the minimum log level.

The LogEventArgs has three properties:

  • LogLevel: level of the message that was logged.
  • Message: the message.
  • Exception: the exception object, if any.

Performance

For simple, static or constant strings, construct and pass the string directly to the logger.

For strings that require IO to be constructed, make sure to pass a System.Func (includes lambdas) to the logger, so that the logging is not causing any useless overhead when the log level is disabled. This way, the IO will not be done.

Furthermore, it also a good idea to always pass debug messages using a System.Func, since debug is most likely disabled in production environments. This prevents some overhead when debugging is disabled, and all debug statements do not need to be removed from the code. This way, the overhead will be absolutely minimal, even with thousands of debug logging statements.

Creating a custom logger

The create a custom logger, the Stylelabs.M.Sdk.Contracts.Logging.ILogger interface needs to be implemented. Then, set the Logger property on the IMClient.

The SDK comes with a base class that greatly reduces the work when implementing ILogger. The base class is Stylelabs.M.Sdk.Models.Logging.LoggerBase. It already handles the firing of events and checking the minimum log level.

Only the following methods will need to implemented:

  • protected void LogDebug(string message)
  • protected void LogInfo(string message)
  • protected void LogWarn(string message)
  • protected void LogError(string message, Exception exception = null)
  • protected void LogError(Exception exception)

SDK loggers

The SDK comes with two logger implementations.

NullLogger

This logger does not process logs at all, but still fires events. This is the default logger on the IMClient.

ConsoleLogger

Writes log messages to the console. By default the messages are templated like this:

DateTime | LogLevel | Message

The template can be disabled by setting UseTemplate to false.

See also

Can we improve this article ? Provide feedback