132
|
1 /*******************************************************************************
|
|
2
|
|
3 copyright: Copyright (c) 2004 Kris Bell. All rights reserved
|
|
4
|
|
5 license: BSD style: $(LICENSE)
|
|
6
|
|
7 version: May 2004: Initial release
|
|
8 version: Feb 2007: Switched to lazy expr
|
|
9
|
|
10 author: Kris
|
|
11
|
|
12 *******************************************************************************/
|
|
13
|
|
14 module tango.util.log.Logger;
|
|
15
|
|
16 private import tango.time.Time;
|
|
17
|
|
18 private import tango.util.log.Appender;
|
|
19
|
|
20 private import tango.util.log.model.ILevel;
|
|
21
|
|
22 /*******************************************************************************
|
|
23
|
|
24 Loggers are named entities, sometimes shared, sometimes specific to
|
|
25 a particular portion of code. The names are generally hierarchical in
|
|
26 nature, using dot notation (with '.') to separate each named section.
|
|
27 For example, a typical name might be something like "mail.send.writer"
|
|
28 ---
|
|
29 import tango.util.log.Log;
|
|
30
|
|
31 auto log = Log.getLogger ("mail.send.writer");
|
|
32
|
|
33 log.info ("an informational message");
|
|
34 log.error ("an exception message: " ~ exception.toString);
|
|
35
|
|
36 etc ...
|
|
37 ---
|
|
38
|
|
39 It is considered good form to pass a logger instance as a function or
|
|
40 class-ctor argument, or to assign a new logger instance during static
|
|
41 class construction. For example: if it were considered appropriate to
|
|
42 have one logger instance per class, each might be constructed like so:
|
|
43 ---
|
|
44 private Logger log;
|
|
45
|
|
46 static this()
|
|
47 {
|
|
48 log = Log.getLogger (nameOfThisClassOrStructOrModule);
|
|
49 }
|
|
50 ---
|
|
51
|
|
52 Messages passed to a Logger are assumed to be pre-formatted. You
|
|
53 may find that the format() methos is handy for collating various
|
|
54 components of the message:
|
|
55 ---
|
|
56 char tmp[128] = void;
|
|
57 ...
|
|
58 log.warn (log.format (tmp, "temperature is {} degrees!", 101));
|
|
59 ---
|
|
60
|
|
61 Note that a provided workspace is used to format the message, which
|
|
62 should generally be located on the stack so as to support multiple
|
|
63 threads of execution. In the example above we indicate assignment as
|
|
64 "tmp = void", although this is an optional attribute (see the language
|
|
65 manual for more information).
|
|
66
|
|
67 To avoid overhead when constructing formatted messages, the logging
|
|
68 system employs lazy expressions such that the message is not constructed
|
|
69 unless the logger is actually active. You can also explicitly check to
|
|
70 see whether a logger is active or not:
|
|
71 ---
|
|
72 if (log.isEnabled (log.Level.Warn))
|
|
73 log.warn (log.format (tmp, "temperature is {} degrees!", 101));
|
|
74 ---
|
|
75
|
|
76 You might optionally configure various layout & appender implementations
|
|
77 to support specific exact rendering needs.
|
|
78
|
|
79 tango.log closely follows both the API and the behaviour as documented
|
|
80 at the official Log4J site, where you'll find a good tutorial. Those
|
|
81 pages are hosted over
|
|
82 <A HREF="http://logging.apache.org/log4j/docs/documentation.html">here</A>.
|
|
83
|
|
84 *******************************************************************************/
|
|
85
|
|
86 public class Logger : ILevel
|
|
87 {
|
|
88 /***********************************************************************
|
|
89
|
|
90 Add a trace message. This is called 'debug' in Log4J but
|
|
91 that is a reserved word in the D language
|
|
92
|
|
93 ***********************************************************************/
|
|
94
|
|
95 abstract Logger trace (lazy char[] exp);
|
|
96
|
|
97 /***********************************************************************
|
|
98
|
|
99 Add an info message
|
|
100
|
|
101 ***********************************************************************/
|
|
102
|
|
103 abstract Logger info (lazy char[] exp);
|
|
104
|
|
105 /***********************************************************************
|
|
106
|
|
107 Add a warning message
|
|
108
|
|
109 ***********************************************************************/
|
|
110
|
|
111 abstract Logger warn (lazy char[] exp);
|
|
112
|
|
113 /***********************************************************************
|
|
114
|
|
115 Add an error message
|
|
116
|
|
117 ***********************************************************************/
|
|
118
|
|
119 abstract Logger error (lazy char[] exp);
|
|
120
|
|
121 /***********************************************************************
|
|
122
|
|
123 Add a fatal message
|
|
124
|
|
125 ***********************************************************************/
|
|
126
|
|
127 abstract Logger fatal (lazy char[] exp);
|
|
128
|
|
129 /***********************************************************************
|
|
130
|
|
131 Append a message to this logger via its appender list.
|
|
132
|
|
133 ***********************************************************************/
|
|
134
|
|
135 abstract Logger append (Level level, lazy char[] exp);
|
|
136
|
|
137 /***********************************************************************
|
|
138
|
|
139 Format text using the formatter configured in the associated
|
|
140 hierarchy (see Hierarchy.setFormat)
|
|
141
|
|
142 ***********************************************************************/
|
|
143
|
|
144 abstract char[] format (char[] buffer, char[] formatStr, ...);
|
|
145
|
|
146 /***********************************************************************
|
|
147
|
|
148 Return the name of this Logger
|
|
149
|
|
150 ***********************************************************************/
|
|
151
|
|
152 abstract char[] name ();
|
|
153
|
|
154 /***********************************************************************
|
|
155
|
|
156 Return the current level assigned to this logger
|
|
157
|
|
158 ***********************************************************************/
|
|
159
|
|
160 abstract Level level ();
|
|
161
|
|
162 /***********************************************************************
|
|
163
|
|
164 Set the activity level of this logger. Levels control how
|
|
165 much information is emitted during runtime, and relate to
|
|
166 each other as follows:
|
|
167 ---
|
|
168 Trace < Info < Warn < Error < Fatal < None
|
|
169 ---
|
|
170 That is, if the level is set to Error, only calls to the
|
|
171 error() and fatal() methods will actually produce output:
|
|
172 all others will be inhibited.
|
|
173
|
|
174 Note that Log4J is a hierarchical environment, and each
|
|
175 logger defaults to inheriting a level from its parent.
|
|
176
|
|
177
|
|
178 ***********************************************************************/
|
|
179
|
|
180 abstract Logger setLevel (Level level = Level.Trace);
|
|
181
|
|
182 /***********************************************************************
|
|
183
|
|
184 same as setLevel (Level), but with additional control over
|
|
185 whether the children are forced to accept the changed level
|
|
186 or not. If 'force' is false, then children adopt the parent
|
|
187 level only if they have their own level set to Level.None
|
|
188
|
|
189 ***********************************************************************/
|
|
190
|
|
191 abstract Logger setLevel (Level level, bool force);
|
|
192
|
|
193 /***********************************************************************
|
|
194
|
|
195 Is this logger enabled for the provided level?
|
|
196
|
|
197 ***********************************************************************/
|
|
198
|
|
199 abstract bool isEnabled (Level level = Level.Fatal);
|
|
200
|
|
201 /***********************************************************************
|
|
202
|
|
203 Return whether this logger uses additive appenders or not.
|
|
204 See setAdditive().
|
|
205
|
|
206 ***********************************************************************/
|
|
207
|
|
208 abstract bool isAdditive ();
|
|
209
|
|
210 /***********************************************************************
|
|
211
|
|
212 Specify whether or not this logger has additive behaviour.
|
|
213 This is enabled by default, and causes a logger to invoke
|
|
214 all appenders within its ancestry (until an ancestor is
|
|
215 found with an additive attribute of false).
|
|
216
|
|
217 ***********************************************************************/
|
|
218
|
|
219 abstract Logger setAdditive (bool enabled);
|
|
220
|
|
221 /***********************************************************************
|
|
222
|
|
223 Add an appender to this logger. You may add multiple
|
|
224 appenders to appropriate loggers, and each of them
|
|
225 will be invoked for that given logger, and for each
|
|
226 of its child loggers (assuming isAdditive() is true
|
|
227 for those children). Note that multiple instances
|
|
228 of the same appender, regardless of where they may
|
|
229 reside within the tree, are not invoked at runtime.
|
|
230 That is, only one from a set of identical loggers
|
|
231 will execute.
|
|
232
|
|
233 Use clearAppenders() to remove all from a given logger.
|
|
234
|
|
235 ***********************************************************************/
|
|
236
|
|
237 abstract Logger addAppender (Appender appender);
|
|
238
|
|
239 /***********************************************************************
|
|
240
|
|
241 Remove all appenders from this logger.
|
|
242
|
|
243 ***********************************************************************/
|
|
244
|
|
245 abstract Logger clearAppenders ();
|
|
246
|
|
247 /***********************************************************************
|
|
248
|
|
249 Get number of milliseconds since this application started
|
|
250
|
|
251 ***********************************************************************/
|
|
252
|
|
253 abstract TimeSpan runtime ();
|
|
254 }
|