1log(n) Logging facility log(n)
2
3
4
5______________________________________________________________________________
6
8 log - Procedures to log messages of libraries and applications.
9
11 package require Tcl 8
12
13 package require log ?1.4?
14
15 ::log::levels
16
17 ::log::lv2longform level
18
19 ::log::lv2color level
20
21 ::log::lv2priority level
22
23 ::log::lv2cmd level
24
25 ::log::lv2channel level
26
27 ::log::lvCompare level1 level2
28
29 ::log::lvSuppress level {suppress 1}
30
31 ::log::lvSuppressLE level {suppress 1}
32
33 ::log::lvIsSuppressed level
34
35 ::log::lvCmd level cmd
36
37 ::log::lvCmdForall cmd
38
39 ::log::lvChannel level chan
40
41 ::log::lvChannelForall chan
42
43 ::log::lvColor level color
44
45 ::log::lvColorForall color
46
47 ::log::log level text
48
49 ::log::logarray level arrayvar ?pattern?
50
51 ::log::loghex level text data
52
53 ::log::logsubst level msg
54
55 ::log::logMsg text
56
57 ::log::logError text
58
59 ::log::Puts level text
60
61______________________________________________________________________________
62
64 The log package provides commands that allow libraries and applications
65 to selectively log information about their internal operation and
66 state.
67
68 To use the package just execute
69
70 package require log
71 log::log notice "Some message"
72
73
74 As can be seen above, each message given to the log facility is associ‐
75 ated with a level determining the importance of the message. The user
76 can then select which levels to log, what commands to use for the log‐
77 ging of each level and the channel to write the message to. In the fol‐
78 lowing example the logging of all message with level debug is deacti‐
79 vated.
80
81 package require log
82 log::lvSuppress debug
83 log::log debug "Unseen message" ; # No output
84
85
86 By default all messages associated with an error-level (emergency,
87 alert, critical, and error) are written to stderr. Messages with any
88 other level are written to stdout. In the following example the log
89 module is reconfigured to write debug messages to stderr too.
90
91 package require log
92 log::lvChannel debug stderr
93 log::log debug "Written to stderr"
94
95
96 Each message level is also associated with a command to use when log‐
97 ging a message with that level. The behaviour above for example relies
98 on the fact that all message levels use by default the standard command
99 ::log::Puts to log any message. In the following example all messages
100 of level notice are given to the non-standard command toText for log‐
101 ging. This disables the channel setting for such messages, assuming
102 that toText does not use it by itself.
103
104 package require log
105 log::lvCmd notice toText
106 log::log notice "Handled by \"toText\""
107
108
109 Another database maintained by this facility is a map from message lev‐
110 els to colors. The information in this database has no influence on the
111 behaviour of the module. It is merely provided as a convenience and in
112 anticipation of the usage of this facility in tk-based application
113 which may want to colorize message logs.
114
116 The following commands are available:
117
118 ::log::levels
119 Returns the names of all known levels, in alphabetical order.
120
121 ::log::lv2longform level
122 Converts any unique abbreviation of a level name to the full
123 level name.
124
125 ::log::lv2color level
126 Converts any level name including unique abbreviations to the
127 corresponding color.
128
129 ::log::lv2priority level
130 Converts any level name including unique abbreviations to the
131 corresponding priority.
132
133 ::log::lv2cmd level
134 Converts any level name including unique abbreviations to the
135 command prefix used to write messages with that level.
136
137 ::log::lv2channel level
138 Converts any level name including unique abbreviations to the
139 channel used by ::log::Puts to write messages with that level.
140
141 ::log::lvCompare level1 level2
142 Compares two levels (including unique abbreviations) with re‐
143 spect to their priority. This command can be used by the -com‐
144 mand option of lsort. The result is one of -1, 0 or 1 or an er‐
145 ror. A result of -1 signals that level1 is of less priority than
146 level2. 0 signals that both levels have the same priority. 1
147 signals that level1 has higher priority than level2.
148
149 ::log::lvSuppress level {suppress 1}
150 (Un)suppresses the output of messages having the specified
151 level. Unique abbreviations for the level are allowed here too.
152
153 ::log::lvSuppressLE level {suppress 1}
154 (Un)suppresses the output of messages having the specified level
155 or one of lesser priority. Unique abbreviations for the level
156 are allowed here too.
157
158 ::log::lvIsSuppressed level
159 Asks the package whether the specified level is currently sup‐
160 pressed. Unique abbreviations of level names are allowed.
161
162 ::log::lvCmd level cmd
163 Defines for the specified level with which command to write the
164 messages having this level. Unique abbreviations of level names
165 are allowed. The command is actually a command prefix and this
166 facility will append 2 arguments before calling it, the level of
167 the message and the message itself, in this order.
168
169 ::log::lvCmdForall cmd
170 Defines for all known levels with which command to write the
171 messages having this level. The command is actually a command
172 prefix and this facility will append 2 arguments before calling
173 it, the level of the message and the message itself, in this or‐
174 der.
175
176 ::log::lvChannel level chan
177 Defines for the specified level into which channel ::log::Puts
178 (the standard command) shall write the messages having this
179 level. Unique abbreviations of level names are allowed. The com‐
180 mand is actually a command prefix and this facility will append
181 2 arguments before calling it, the level of the message and the
182 message itself, in this order.
183
184 ::log::lvChannelForall chan
185 Defines for all known levels with which which channel
186 ::log::Puts (the standard command) shall write the messages hav‐
187 ing this level. The command is actually a command prefix and
188 this facility will append 2 arguments before calling it, the
189 level of the message and the message itself, in this order.
190
191 ::log::lvColor level color
192 Defines for the specified level the color to return for it in a
193 call to ::log::lv2color. Unique abbreviations of level names are
194 allowed.
195
196 ::log::lvColorForall color
197 Defines for all known levels the color to return for it in a
198 call to ::log::lv2color. Unique abbreviations of level names are
199 allowed.
200
201 ::log::log level text
202 Log a message according to the specifications for commands,
203 channels and suppression. In other words: The command will do
204 nothing if the specified level is suppressed. If it is not sup‐
205 pressed the actual logging is delegated to the specified com‐
206 mand. If there is no command specified for the level the message
207 won't be logged. The standard command ::log::Puts will write the
208 message to the channel specified for the given level. If no
209 channel is specified for the level the message won't be logged.
210 Unique abbreviations of level names are allowed. Errors in the
211 actual logging command are not caught, but propagated to the
212 caller, as they may indicate misconfigurations of the log facil‐
213 ity or errors in the callers code itself.
214
215 ::log::logarray level arrayvar ?pattern?
216 Like ::log::log, but logs the contents of the specified array
217 variable arrayvar, possibly restricted to entries matching the
218 pattern. The pattern defaults to * (i.e. all entries) if none
219 was specified.
220
221 ::log::loghex level text data
222 Like ::log::log, but assumes that data contains binary data. It
223 converts this into a mixed hex/ascii representation before writ‐
224 ing them to the log.
225
226 ::log::logsubst level msg
227 Like ::log::log, but msg may contain substitutions and variable
228 references, which are evaluated in the caller scope first. The
229 purpose of this command is to avoid overhead in the non-logging
230 case, if the log message building is expensive. Any substitu‐
231 tion errors raise an error in the command execution. The fol‐
232 lowing example shows an xml text representation, which is only
233 generated in debug mode:
234
235
236 log::logsubst debug {XML of node $node is '[$node toXml]'}
237
238
239 ::log::logMsg text
240 Convenience wrapper around ::log::log. Equivalent to ::log::log
241 info text.
242
243 ::log::logError text
244 Convenience wrapper around ::log::log. Equivalent to ::log::log
245 error text.
246
247 ::log::Puts level text
248 The standard log command, it writes messages and their levels to
249 user-specified channels. Assumes that the suppression checks
250 were done by the caller. Expects full level names, abbreviations
251 are not allowed.
252
254 The package currently defines the following log levels, the level of
255 highest importance listed first.
256
257 • emergency
258
259 • alert
260
261 • critical
262
263 • error
264
265 • warning
266
267 • notice
268
269 • info
270
271 • debug
272
273 Note that by default all messages with levels warning down to debug are
274 suppressed. This is done intentionally, because (we believe that) in
275 most situations debugging output is not wanted. Most people wish to
276 have such output only when actually debugging an application.
277
279 This document, and the package it describes, will undoubtedly contain
280 bugs and other problems. Please report such in the category log of the
281 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
282 report any ideas for enhancements you may have for either package
283 and/or documentation.
284
285 When proposing code changes, please provide unified diffs, i.e the out‐
286 put of diff -u.
287
288 Note further that attachments are strongly preferred over inlined
289 patches. Attachments can be made by going to the Edit form of the
290 ticket immediately after its creation, and then using the left-most
291 button in the secondary navigation bar.
292
294 log, log level, message, message level
295
297 Programming tools
298
300 Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
301
302
303
304
305tcllib 1.4 log(n)