Boost License 1.0.

Robert burner Schadek

Basic Logging

Message logging is a common approach to expose runtime information of aprogram. Logging should be easy, but also flexible and powerful, thereforeD provides a standard interface for logging.The easiest way to create a log message is to write:

import std.logger;void main() {    info("Hello World");}

This will print a message to thestderr device. The message will containthe filename, the line number, the name of the surrounding function, the timeand the message.More complex log call can go along the lines like:

log("Logging to the sharedLog with its default LogLevel");logf(LogLevel.info, 5 < 6,"%s to the sharedLog with its LogLevel.info","Logging");info("Logging to the sharedLog with its info LogLevel");warning(5 < 6,"Logging to the sharedLog with its LogLevel.warning if 5 is less than 6");error("Logging to the sharedLog with its error LogLevel");errorf("Logging %s the sharedLog %s its error LogLevel","to","with");critical("Logging to the"," sharedLog with its error LogLevel");fatal("Logging to the sharedLog with its fatal LogLevel");auto fLogger =new FileLogger("NameOfTheLogFile");fLogger.log("Logging to the fileLogger with its default LogLevel");fLogger.info("Logging to the fileLogger with its default LogLevel");fLogger.warning(5 < 6,"Logging to the fileLogger with its LogLevel.warning if 5 is less than 6");fLogger.warningf(5 < 6,"Logging to the fileLogger with its LogLevel.warning if %s is %s than 6", 5,"less");fLogger.critical("Logging to the fileLogger with its info LogLevel");fLogger.log(LogLevel.trace, 5 < 6,"Logging to the fileLogger"," with its default LogLevel if 5 is less than 6");fLogger.fatal("Logging to the fileLogger with its warning LogLevel");

Additionally, this example shows how a newFileLogger is created.IndividualLogger and the global log functions share commonly namedfunctions to log data.The names of the functions are as follows:

• log
• trace
• info
• warning
• error
• critical
• fatal

The defaultLogger will by default log tostderr and has a defaultLogLevel ofLogLevel.info. The default Logger can be accessed byusing the property calledsharedLog. This property is a reference to thecurrent defaultLogger. This reference can be used to assign a newdefaultLogger.

sharedLog =newshared FileLogger("New_Default_Log_File.log");

AdditionalLogger can be created by creating a new instance of therequiredLogger.

Logging Fundamentals

LogLevel

TheLogLevel of a log call can be defined in two ways. The first is bycallinglog and passing theLogLevel explicitly as the first argument.The second way of setting theLogLevel of alog call, is by calling eithertrace,info,warning,critical, orfatal. The log call will then have the respectiveLogLevel. If noLogLevel is defined the log call will use thecurrentLogLevel of the usedLogger. If data is logged withLogLevelfatal by default anError will be thrown.This behaviour can be modified by using the memberfatalHandler toassign a custom delegate to handle log call withLogLevelfatal.

Conditional Logging

Conditional logging can be achieved be passing abool as firstargument to a log function. If conditional logging is used the condition mustbetrue in order to have the log message logged.In order to combine an explicitLogLevel passing with conditionallogging, theLogLevel has to be passed as first argument followed by thebool.

Filtering Log Messages

Messages are logged if theLogLevel of the log message is greater than orequal to theLogLevel of the usedLogger and additionally if theLogLevel of the log message is greater than or equal to the globalLogLevel.If a condition is passed into the log call, this condition must be true.The globalLogLevel is accessible by usingglobalLogLevel.To assign aLogLevel of aLogger use thelogLevel property ofthe logger.

Printf Style Logging

Ifprintf-style logging is needed add af to the logging call, such asmyLogger.infof("Hello %s", "world"); orfatalf("errno %d", 1337).The additionalf appended to the function name enablesprintf-stylelogging for all combinations of explicitLogLevel and conditionallogging functions and methods.

Thread Local Redirection

Calls to the free standing log functions are not directly forwarded to theglobalLoggersharedLog. Actually, a thread localLogger oftypeStdForwardLogger processes the log call and then, by default, forwardsthe createdLogger.LogEntry to thesharedLogLogger.The thread localLogger is accessible by thestdThreadLocalLogproperty. This property allows to assign user definedLogger. The defaultLogLevel of thestdThreadLocalLogLogger isLogLevel.alland it will therefore forward all messages to thesharedLogLogger.TheLogLevel of thestdThreadLocalLog can be used to filter logcalls before they reach thesharedLogLogger.

User Defined Logger

To customize theLogger behavior, create a newclass that inherits fromthe abstractLoggerclass, and implements thewriteLogMsgmethod.

class MyCustomLogger : Logger{this(LogLevel lv) @safe    {super(lv);    }overridevoid writeLogMsg(ref LogEntry payload)    {// log message in my custom way    }}autologger =new MyCustomLogger(LogLevel.info);logger.log("Awesome log message with LogLevel.info");

To gain more precise control over the logging process, additionally tooverriding thewriteLogMsg method the methodsbeginLogMsg,logMsgPart andfinishLogMsg can be overridden.

Provided Logger

By default fourLogger implementations are given. TheFileLoggerlogs data to files. It can also be used to log tostdout andstderras these devices are files as well. ALogger that logs tostdout cantherefore be created bynew FileLogger(stdout).TheMultiLogger is basically an associative array ofstrings toLogger. It propagates log calls to its storedLogger. TheArrayLogger contains an array ofLogger and also propagates logcalls to its storedLogger. TheNullLogger does not do anything. Itwill never log a message and will never throw on a log call withLogLevelerror.