1 /** 2 Implements logging facilities. 3 4 Copyright: Copyright Robert "burner" Schadek 2013 -- 5 License: <a href="http://www.boost.org/LICENSE_1_0.txt">Boost License 1.0</a>. 6 Authors: $(HTTP www.svs.informatik.uni-oldenburg.de/60865.html, Robert burner Schadek) 7 8 $(H3 Basic Logging) 9 10 Message logging is a common approach to expose runtime information of a 11 program. Logging should be easy, but also flexible and powerful, therefore 12 $(D D) provides a standard interface for logging. 13 14 The easiest way to create a log message is to write: 15 ------------- 16 import std.experimental.logger; 17 18 void main() { 19 log("Hello World"); 20 } 21 ------------- 22 This will print a message to the $(D stderr) device. The message will contain 23 the filename, the line number, the name of the surrounding function, the time 24 and the message. 25 26 More complex log call can go along the lines like: 27 ------------- 28 log("Logging to the sharedLog with its default LogLevel"); 29 logf(LogLevel.info, 5 < 6, "%s to the sharedLog with its LogLevel.info", "Logging"); 30 info("Logging to the sharedLog with its info LogLevel"); 31 warning(5 < 6, "Logging to the sharedLog with its LogLevel.warning if 5 is less than 6"); 32 error("Logging to the sharedLog with its error LogLevel"); 33 errorf("Logging %s the sharedLog %s its error LogLevel", "to", "with"); 34 critical("Logging to the"," sharedLog with its error LogLevel"); 35 fatal("Logging to the sharedLog with its fatal LogLevel"); 36 37 auto fLogger = new FileLogger("NameOfTheLogFile"); 38 fLogger.log("Logging to the fileLogger with its default LogLevel"); 39 fLogger.info("Logging to the fileLogger with its default LogLevel"); 40 fLogger.warning(5 < 6, "Logging to the fileLogger with its LogLevel.warning if 5 is less than 6"); 41 fLogger.warningf(5 < 6, "Logging to the fileLogger with its LogLevel.warning if %s is %s than 6", 5, "less"); 42 fLogger.critical("Logging to the fileLogger with its info LogLevel"); 43 fLogger.log(LogLevel.trace, 5 < 6, "Logging to the fileLogger"," with its default LogLevel if 5 is less than 6"); 44 fLogger.fatal("Logging to the fileLogger with its warning LogLevel"); 45 ------------- 46 Additionally, this example shows how a new $(D FileLogger) is created. 47 Individual $(D Logger) and the global log functions share commonly named 48 functions to log data. 49 50 The names of the functions are as follows: 51 $(UL 52 $(LI $(D log)) 53 $(LI $(D trace)) 54 $(LI $(D info)) 55 $(LI $(D warning)) 56 $(LI $(D critical)) 57 $(LI $(D fatal)) 58 ) 59 The default $(D Logger) will by default log to $(D stderr) and has a default 60 $(D LogLevel) of $(D LogLevel.all). The default Logger can be accessed by 61 using the property called $(D sharedLog). This property is a reference to the 62 current default $(D Logger). This reference can be used to assign a new 63 default $(D Logger). 64 ------------- 65 sharedLog = new FileLogger("New_Default_Log_File.log"); 66 ------------- 67 68 Additional $(D Logger) can be created by creating a new instance of the 69 required $(D Logger). 70 71 $(H3 Logging Fundamentals) 72 $(H4 LogLevel) 73 The $(D LogLevel) of a log call can be defined in two ways. The first is by 74 calling $(D log) and passing the $(D LogLevel) explicitly as the first argument. 75 The second way of setting the $(D LogLevel) of a 76 log call, is by calling either $(D trace), $(D info), $(D warning), 77 $(D critical), or $(D fatal). The log call will then have the respective 78 $(D LogLevel). If no $(D LogLevel) is defined the log call will use the 79 current $(D LogLevel) of the used $(D Logger). If data is logged with 80 $(D LogLevel) $(D fatal) by default an $(D Error) will be thrown. 81 This behaviour can be modified by using the member $(D fatalHandler) to 82 assign a custom delegate to handle log call with $(D LogLevel) $(D fatal). 83 84 $(H4 Conditional Logging) 85 Conditional logging can be achieved be passing a $(D bool) as first 86 argument to a log function. If conditional logging is used the condition must 87 be $(D true) in order to have the log message logged. 88 89 In order to combine an explicit $(D LogLevel) passing with conditional 90 logging, the $(D LogLevel) has to be passed as first argument followed by the 91 $(D bool). 92 93 $(H4 Filtering Log Messages) 94 Messages are logged if the $(D LogLevel) of the log message is greater than or 95 equal to the $(D LogLevel) of the used $(D Logger) and additionally if the 96 $(D LogLevel) of the log message is greater than or equal to the global $(D LogLevel). 97 If a condition is passed into the log call, this condition must be true. 98 99 The global $(D LogLevel) is accessible by using $(D globalLogLevel). 100 To assign a $(D LogLevel) of a $(D Logger) use the $(D logLevel) property of 101 the logger. 102 103 $(H4 Printf Style Logging) 104 If $(D printf)-style logging is needed add a $(B f) to the logging call, such as 105 $(D myLogger.infof("Hello %s", "world");) or $(D fatalf("errno %d", 1337)). 106 The additional $(B f) appended to the function name enables $(D printf)-style 107 logging for all combinations of explicit $(D LogLevel) and conditional 108 logging functions and methods. 109 110 $(H4 Thread Local Redirection) 111 Calls to the free standing log functions are not directly forwarded to the 112 global $(D Logger) $(D sharedLog). Actually, a thread local $(D Logger) of 113 type $(D StdForwardLogger) processes the log call and then, by default, forwards 114 the created $(D Logger.LogEntry) to the $(D sharedLog) $(D Logger). 115 The thread local $(D Logger) is accessible by the $(D stdThreadLocalLog) 116 property. This property allows to assign user defined $(D Logger). The default 117 $(D LogLevel) of the $(D stdThreadLocalLog) $(D Logger) is $(D LogLevel.all) 118 and it will therefore forward all messages to the $(D sharedLog) $(D Logger). 119 The $(D LogLevel) of the $(D stdThreadLocalLog) can be used to filter log 120 calls before they reach the $(D sharedLog) $(D Logger). 121 122 $(H3 User Defined Logger) 123 To customize the $(D Logger) behavior, create a new $(D class) that inherits from 124 the abstract $(D Logger) $(D class), and implements the $(D writeLogMsg) 125 method. 126 ------------- 127 class MyCustomLogger : Logger 128 { 129 this(LogLevel lv) @safe 130 { 131 super(lv); 132 } 133 134 override void writeLogMsg(ref LogEntry payload) 135 { 136 // log message in my custom way 137 } 138 } 139 140 auto logger = new MyCustomLogger(LogLevel.info); 141 logger.log("Awesome log message with LogLevel.info"); 142 ------------- 143 144 To gain more precise control over the logging process, additionally to 145 overriding the $(D writeLogMsg) method the methods $(D beginLogMsg), 146 $(D logMsgPart) and $(D finishLogMsg) can be overridden. 147 148 $(H3 Compile Time Disabling of $(D Logger)) 149 In order to disable logging at compile time, pass $(D StdLoggerDisableLogging) as a 150 version argument to the $(D D) compiler when compiling your program code. 151 This will disable all logging functionality. 152 Specific $(D LogLevel) can be disabled at compile time as well. 153 In order to disable logging with the $(D trace) $(D LogLevel) pass 154 $(D StdLoggerDisableTrace) as a version. 155 The following table shows which version statement disables which 156 $(D LogLevel). 157 $(TABLE 158 $(TR $(TD $(D LogLevel.trace) ) $(TD StdLoggerDisableTrace)) 159 $(TR $(TD $(D LogLevel.info) ) $(TD StdLoggerDisableInfo)) 160 $(TR $(TD $(D LogLevel.warning) ) $(TD StdLoggerDisableWarning)) 161 $(TR $(TD $(D LogLevel.error) ) $(TD StdLoggerDisableError)) 162 $(TR $(TD $(D LogLevel.critical) ) $(TD StdLoggerDisableCritical)) 163 $(TR $(TD $(D LogLevel.fatal) ) $(TD StdLoggerDisableFatal)) 164 ) 165 Such a version statement will only disable logging in the associated compile 166 unit. 167 168 $(H3 Provided Logger) 169 By default four $(D Logger) implementations are given. The $(D FileLogger) 170 logs data to files. It can also be used to log to $(D stdout) and $(D stderr) 171 as these devices are files as well. A $(D Logger) that logs to $(D stdout) can 172 therefore be created by $(D new FileLogger(stdout)). 173 The $(D MultiLogger) is basically an associative array of $(D string)s to 174 $(D Logger). It propagates log calls to its stored $(D Logger). The 175 $(D ArrayLogger) contains an array of $(D Logger) and also propagates log 176 calls to its stored $(D Logger). The $(D NullLogger) does not do anything. It 177 will never log a message and will never throw on a log call with $(D LogLevel) 178 $(D error). 179 */ 180 module std.experimental.logger; 181 182 public import std.experimental.logger.core; 183 public import std.experimental.logger.filelogger; 184 public import std.experimental.logger.multilogger; 185 public import std.experimental.logger.nulllogger; 186