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