1log(n) Logging facility log(n)
2______________________________________________________________________________
6
8 log - Procedures to log messages of libraries and applications.
9
11 package require Tcl 8
12 package require log ?1.4?
14 ::log::levels
16 ::log::lv2longform level
18 ::log::lv2color level
20 ::log::lv2priority level
22 ::log::lv2cmd level
24 ::log::lv2channel level
26 ::log::lvCompare level1 level2
28 ::log::lvSuppress level {suppress 1}
30 ::log::lvSuppressLE level {suppress 1}
32 ::log::lvIsSuppressed level
34 ::log::lvCmd level cmd
36 ::log::lvCmdForall cmd
38 ::log::lvChannel level chan
40 ::log::lvChannelForall chan
42 ::log::lvColor level color
44 ::log::lvColorForall color
46 ::log::log level text
48 ::log::logarray level arrayvar ?pattern?
50 ::log::loghex level text data
52 ::log::logsubst level msg
54 ::log::logMsg text
56 ::log::logError text
58 ::log::Puts level text
60______________________________________________________________________________
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 To use the package just execute
69 package require log
71 log::log notice "Some message"
72 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 package require log
82 log::lvSuppress debug
83 log::log debug "Unseen message" ; # No output
84 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 package require log
92 log::lvChannel debug stderr
93 log::log debug "Written to stderr"
94 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 package require log
105 log::lvCmd notice toText
106 log::log notice "Handled by \"toText\""
107 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 ::log::levels
119 Returns the names of all known levels, in alphabetical order.
120 ::log::lv2longform level
122 Converts any unique abbreviation of a level name to the full
123 level name.
124 ::log::lv2color level
126 Converts any level name including unique abbreviations to the
127 corresponding color.
128 ::log::lv2priority level
130 Converts any level name including unique abbreviations to the
131 corresponding priority.
132 ::log::lv2cmd level
134 Converts any level name including unique abbreviations to the
135 command prefix used to write messages with that level.
136 ::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 ::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 ::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 ::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 ::log::lvIsSuppressed level
159 Asks the package whether the specified level is currently sup‐
160 pressed. Unique abbreviations of level names are allowed.
161 ::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 ::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 ::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 ::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 ::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 ::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 ::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 ::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 ::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 ::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 log::logsubst debug {XML of node $node is '[$node toXml]'}
237 ::log::logMsg text
240 Convenience wrapper around ::log::log. Equivalent to ::log::log
241 info text.
242 ::log::logError text
244 Convenience wrapper around ::log::log. Equivalent to ::log::log
245 error text.
246 ::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 • emergency
258 • alert
260 • critical
262 • error
264 • warning
266 • notice
268 • info
270 • debug
272 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 When proposing code changes, please provide unified diffs, i.e the out‐
286 put of diff -u.
287 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>
301tcllib 1.4 log(n)