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.3?
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::logMsg text
54 ::log::logError text
56 ::log::Puts level text
58______________________________________________________________________________
60
62 The log package provides commands that allow libraries and applications
63 to selectively log information about their internal operation and
64 state.
65 To use the package just execute
67 package require log
69 log::log notice "Some message"
70 As can be seen above, each message given to the log facility is associ‐
73 ated with a level determining the importance of the message. The user
74 can then select which levels to log, what commands to use for the log‐
75 ging of each level and the channel to write the message to. In the fol‐
76 lowing example the logging of all message with level debug is deacti‐
77 vated.
78 package require log
80 log::lvSuppress debug
81 log::log debug "Unseen message" ; # No output
82 By default all messages associated with an error-level (emergency,
85 alert, critical, and error) are written to stderr. Messages with any
86 other level are written to stdout. In the following example the log
87 module is reconfigured to write debug messages to stderr too.
88 package require log
90 log::lvChannel debug stderr
91 log::log debug "Written to stderr"
92 Each message level is also associated with a command to use when log‐
95 ging a message with that level. The behaviour above for example relies
96 on the fact that all message levels use by default the standard command
97 ::log::Puts to log any message. In the following example all messages
98 of level notice are given to the non-standard command toText for log‐
99 ging. This disables the channel setting for such messages, assuming
100 that toText does not use it by itself.
101 package require log
103 log::lvCmd notice toText
104 log::log notice "Handled by \"toText\""
105 Another database maintained by this facility is a map from message lev‐
108 els to colors. The information in this database has no influence on the
109 behaviour of the module. It is merely provided as a convenience and in
110 anticipation of the usage of this facility in tk-based application
111 which may want to colorize message logs.
112
114 The following commands are available:
115 ::log::levels
117 Returns the names of all known levels, in alphabetical order.
118 ::log::lv2longform level
120 Converts any unique abbreviation of a level name to the full
121 level name.
122 ::log::lv2color level
124 Converts any level name including unique abbreviations to the
125 corresponding color.
126 ::log::lv2priority level
128 Converts any level name including unique abbreviations to the
129 corresponding priority.
130 ::log::lv2cmd level
132 Converts any level name including unique abbreviations to the
133 command prefix used to write messages with that level.
134 ::log::lv2channel level
136 Converts any level name including unique abbreviations to the
137 channel used by ::log::Puts to write messages with that level.
138 ::log::lvCompare level1 level2
140 Compares two levels (including unique abbreviations) with
141 respect to their priority. This command can be used by the -com‐
142 mand option of lsort. The result is one of -1, 0 or 1 or an
143 error. A result of -1 signals that level1 is of less priority
144 than level2. 0 signals that both levels have the same priority.
145 1 signals that level1 has higher priority than level2.
146 ::log::lvSuppress level {suppress 1}
148 ] (Un)suppresses the output of messages having the specified
149 level. Unique abbreviations for the level are allowed here too.
150 ::log::lvSuppressLE level {suppress 1}
152 ] (Un)suppresses the output of messages having the specified
153 level or one of lesser priority. Unique abbreviations for the
154 level are allowed here too.
155 ::log::lvIsSuppressed level
157 Asks the package whether the specified level is currently sup‐
158 pressed. Unique abbreviations of level names are allowed.
159 ::log::lvCmd level cmd
161 Defines for the specified level with which command to write the
162 messages having this level. Unique abbreviations of level names
163 are allowed. The command is actually a command prefix and this
164 facility will append 2 arguments before calling it, the level of
165 the message and the message itself, in this order.
166 ::log::lvCmdForall cmd
168 Defines for all known levels with which command to write the
169 messages having this level. The command is actually a command
170 prefix and this facility will append 2 arguments before calling
171 it, the level of the message and the message itself, in this
172 order.
173 ::log::lvChannel level chan
175 Defines for the specified level into which channel ::log::Puts
176 (the standard command) shall write the messages having this
177 level. Unique abbreviations of level names are allowed. The com‐
178 mand is actually a command prefix and this facility will append
179 2 arguments before calling it, the level of the message and the
180 message itself, in this order.
181 ::log::lvChannelForall chan
183 Defines for all known levels with which which channel
184 ::log::Puts (the standard command) shall write the messages hav‐
185 ing this level. The command is actually a command prefix and
186 this facility will append 2 arguments before calling it, the
187 level of the message and the message itself, in this order.
188 ::log::lvColor level color
190 Defines for the specified level the color to return for it in a
191 call to ::log::lv2color. Unique abbreviations of level names are
192 allowed.
193 ::log::lvColorForall color
195 Defines for all known levels the color to return for it in a
196 call to ::log::lv2color. Unique abbreviations of level names are
197 allowed.
198 ::log::log level text
200 Log a message according to the specifications for commands,
201 channels and suppression. In other words: The command will do
202 nothing if the specified level is suppressed. If it is not sup‐
203 pressed the actual logging is delegated to the specified com‐
204 mand. If there is no command specified for the level the message
205 won't be logged. The standard command ::log::Puts will write the
206 message to the channel specified for the given level. If no
207 channel is specified for the level the message won't be logged.
208 Unique abbreviations of level names are allowed. Errors in the
209 actual logging command are not caught, but propagated to the
210 caller, as they may indicate misconfigurations of the log facil‐
211 ity or errors in the callers code itself.
212 ::log::logarray level arrayvar ?pattern?
214 Like ::log::log, but logs the contents of the specified array
215 variable arrayvar, possibly restricted to entries matching the
216 pattern. The pattern defaults to * (i.e. all entries) if none
217 was specified.
218 ::log::loghex level text data
220 Like ::log::log, but assumes that data contains binary data. It
221 converts this into a mixed hex/ascii representation before writ‐
222 ing them to the log.
223 ::log::logMsg text
225 Convenience wrapper around ::log::log. Equivalent to ::log::log
226 info text.
227 ::log::logError text
229 Convenience wrapper around ::log::log. Equivalent to ::log::log
230 error text.
231 ::log::Puts level text
233 The standard log command, it writes messages and their levels to
234 user-specified channels. Assumes that the suppression checks
235 were done by the caller. Expects full level names, abbreviations
236 are not allowed.
237
239 The package currently defines the following log levels, the level of
240 highest importance listed first.
241 · emergency
243 · alert
245 · critical
247 · error
249 · warning
251 · notice
253 · info
255 · debug
257 Note that by default all messages with levels warning down to debug are
259 suppressed. This is done intentionally, because (we believe that) in
260 most situations debugging output is not wanted. Most people wish to
261 have such output only when actually debugging an application.
262
264 This document, and the package it describes, will undoubtedly contain
265 bugs and other problems. Please report such in the category log of the
266 Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also
267 report any ideas for enhancements you may have for either package
268 and/or documentation.
269 When proposing code changes, please provide unified diffs, i.e the out‐
271 put of diff -u.
272 Note further that attachments are strongly preferred over inlined
274 patches. Attachments can be made by going to the Edit form of the
275 ticket immediately after its creation, and then using the left-most
276 button in the secondary navigation bar.
277
279 log, log level, message, message level
280
282 Programming tools
283
285 Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
286tcllib 1.3 log(n)