libphobos/src/std/logger/package.d

   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;