1log(n)                         Logging facility                         log(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       log - Procedures to log messages of libraries and applications.
9

SYNOPSIS

11       package require Tcl  8
12
13       package require log  ?1.3?
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::logMsg text
54
55       ::log::logError text
56
57       ::log::Puts level text
58
59______________________________________________________________________________
60

DESCRIPTION

62       The log package provides commands that allow libraries and applications
63       to selectively log  information  about  their  internal  operation  and
64       state.
65
66       To use the package just execute
67
68                  package require log
69                  log::log notice "Some message"
70
71
72       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
79                  package require log
80                  log::lvSuppress debug
81                  log::log debug "Unseen message" ; # No output
82
83
84       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
89                  package require log
90                  log::lvChannel debug stderr
91                  log::log debug "Written to stderr"
92
93
94       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
102                  package require log
103                  log::lvCmd notice toText
104                  log::log notice "Handled by \"toText\""
105
106
107       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

API

114       The following commands are available:
115
116       ::log::levels
117              Returns the names of all known levels, in alphabetical order.
118
119       ::log::lv2longform level
120              Converts  any  unique  abbreviation  of a level name to the full
121              level name.
122
123       ::log::lv2color level
124              Converts any level name including unique  abbreviations  to  the
125              corresponding color.
126
127       ::log::lv2priority level
128              Converts  any  level  name including unique abbreviations to the
129              corresponding priority.
130
131       ::log::lv2cmd level
132              Converts any level name including unique  abbreviations  to  the
133              command prefix used to write messages with that level.
134
135       ::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
139       ::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
147       ::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
151       ::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
156       ::log::lvIsSuppressed level
157              Asks the package whether the specified level is  currently  sup‐
158              pressed. Unique abbreviations of level names are allowed.
159
160       ::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
167       ::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
174       ::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
182       ::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
189       ::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
194       ::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
199       ::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
213       ::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
219       ::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
224       ::log::logMsg text
225              Convenience wrapper around ::log::log.  Equivalent to ::log::log
226              info text.
227
228       ::log::logError text
229              Convenience wrapper around ::log::log.  Equivalent to ::log::log
230              error text.
231
232       ::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

LEVELS

239       The  package  currently  defines the following log levels, the level of
240       highest importance listed first.
241
242       ·      emergency
243
244       ·      alert
245
246       ·      critical
247
248       ·      error
249
250       ·      warning
251
252       ·      notice
253
254       ·      info
255
256       ·      debug
257
258       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

BUGS, IDEAS, FEEDBACK

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
270       When proposing code changes, please provide unified diffs, i.e the out‐
271       put of diff -u.
272
273       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

KEYWORDS

279       log, log level, message, message level
280

CATEGORY

282       Programming tools
283
285       Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>
286
287
288
289
290tcllib                                1.3                               log(n)
Impressum