


log(n)                   Logging facility                  log(n)


______________________________________________________________________________

NAME
       log - Procedures to log messages of libraries and applications.

SYNOPSIS
       package require Tcl  8

       package require log  ?1.3?

       ::log::levels

       ::log::lv2longform level

       ::log::lv2color level

       ::log::lv2priority level

       ::log::lv2cmd level

       ::log::lv2channel level

       ::log::lvCompare level1 level2

       ::log::lvSuppress level {suppress 1}

       ::log::lvSuppressLE level {suppress 1}

       ::log::lvIsSuppressed level

       ::log::lvCmd level cmd

       ::log::lvCmdForall cmd

       ::log::lvChannel level chan

       ::log::lvChannelForall chan

       ::log::lvColor level color

       ::log::lvColorForall color

       ::log::log level text

       ::log::logarray level arrayvar ?pattern?

       ::log::loghex level text data

       ::log::logMsg text

       ::log::logError text

       ::log::Puts level text




log                            1.3                              1





log(n)                   Logging facility                  log(n)


_________________________________________________________________

DESCRIPTION
       The log package provides commands that allow libraries and applications
       to selectively log  information  about  their  internal  operation  and
       state.

       To use the package just execute


           package require log
           log::log notice "Some message"


       As can be seen above, each message given to the log facility is associ-
       ated with a level determining the importance of the message.  The  user
       can  then select which levels to log, what commands to use for the log-
       ging of each level and the channel to write the message to. In the fol-
       lowing  example  the logging of all message with level debug is deacti-
       vated.


           package require log
           log::lvSuppress debug
           log::log debug "Unseen message" ; # No output


       By default all messages  associated  with  an  error-level  (emergency,
       alert,  critical,  and  error) are written to stderr. Messages with any
       other level are written to stdout. In the  following  example  the  log
       module is reconfigured to write debug messages to stderr too.


           package require log
           log::lvChannel debug stderr
           log::log debug "Written to stderr"


       Each  message  level is also associated with a command to use when log-
       ging a message with that level. The behaviour above for example  relies
       on the fact that all message levels use by default the standard command
       ::log::Puts to log any message. In the following example  all  messages
       of  level  notice are given to the non-standard command toText for log-
       ging. This disables the channel setting  for  such  messages,  assuming
       that toText does not use it by itself.


           package require log
           log::lvCmd notice toText
           log::log notice "Handled by \"toText\""


       Another database maintained by this facility is a map from message lev-
       els to colors. The information in this database has no influence on the



log                            1.3                              2





log(n)                   Logging facility                  log(n)


       behaviour  of the module. It is merely provided as a convenience and in
       anticipation of the usage of  this  facility  in  tk-based  application
       which may want to colorize message logs.

API
       The following commands are available:

       ::log::levels
              Returns the names of all known levels, in alphabetical order.

       ::log::lv2longform level
              Converts  any  unique  abbreviation  of a level name to the full
              level name.

       ::log::lv2color level
              Converts any level name including unique  abbreviations  to  the
              corresponding color.

       ::log::lv2priority level
              Converts  any  level  name including unique abbreviations to the
              corresponding priority.

       ::log::lv2cmd level
              Converts any level name including unique  abbreviations  to  the
              command prefix used to write messages with that level.

       ::log::lv2channel level
              Converts  any  level  name including unique abbreviations to the
              channel used by ::log::Puts to write messages with that level.

       ::log::lvCompare level1 level2
              Compares  two  levels  (including  unique  abbreviations)   with
              respect to their priority. This command can be used by the -com-
              mand option of lsort. The result is one of -1,  0  or  1  or  an
              error.  A  result  of -1 signals that level1 is of less priority
              than level2. 0 signals that both levels have the same  priority.
              1 signals that level1 has higher priority than level2.

       ::log::lvSuppress level {suppress 1}
              ]  (Un)suppresses  the  output  of messages having the specified
              level. Unique abbreviations for the level are allowed here  too.

       ::log::lvSuppressLE level {suppress 1}
              ]  (Un)suppresses  the  output  of messages having the specified
              level or one of lesser priority. Unique  abbreviations  for  the
              level are allowed here too.

       ::log::lvIsSuppressed level
              Asks  the  package whether the specified level is currently sup-
              pressed. Unique abbreviations of level names are allowed.

       ::log::lvCmd level cmd
              Defines for the specified level with which command to write  the
              messages  having this level. Unique abbreviations of level names



log                            1.3                              3





log(n)                   Logging facility                  log(n)


              are allowed. The command is actually a command prefix  and  this
              facility will append 2 arguments before calling it, the level of
              the message and the message itself, in this order.

       ::log::lvCmdForall cmd
              Defines for all known levels with which  command  to  write  the
              messages  having  this  level. The command is actually a command
              prefix and this facility will append 2 arguments before  calling
              it,  the  level  of  the message and the message itself, in this
              order.

       ::log::lvChannel level chan
              Defines for the specified level into which  channel  ::log::Puts
              (the  standard  command)  shall  write  the messages having this
              level. Unique abbreviations of level names are allowed. The com-
              mand  is actually a command prefix and this facility will append
              2 arguments before calling it, the level of the message and  the
              message itself, in this order.

       ::log::lvChannelForall chan
              Defines   for   all   known  levels  with  which  which  channel
              ::log::Puts (the standard command) shall write the messages hav-
              ing  this  level.  The  command is actually a command prefix and
              this facility will append 2 arguments  before  calling  it,  the
              level of the message and the message itself, in this order.

       ::log::lvColor level color
              Defines  for the specified level the color to return for it in a
              call to ::log::lv2color. Unique abbreviations of level names are
              allowed.

       ::log::lvColorForall color
              Defines  for  all  known  levels the color to return for it in a
              call to ::log::lv2color. Unique abbreviations of level names are
              allowed.

       ::log::log level text
              Log  a  message  according  to  the specifications for commands,
              channels and suppression. In other words: The  command  will  do
              nothing  if the specified level is suppressed. If it is not sup-
              pressed the actual logging is delegated to  the  specified  com-
              mand. If there is no command specified for the level the message
              won't be logged. The standard command ::log::Puts will write the
              message  to  the  channel  specified  for the given level. If no
              channel is specified for the level the message won't be  logged.
              Unique  abbreviations  of level names are allowed. Errors in the
              actual logging command are not caught,  but  propagated  to  the
              caller, as they may indicate misconfigurations of the log facil-
              ity or errors in the callers code itself.

       ::log::logarray level arrayvar ?pattern?
              Like ::log::log, but logs the contents of  the  specified  array
              variable  arrayvar,  possibly restricted to entries matching the
              pattern. The pattern defaults to * (i.e. all  entries)  if  none



log                            1.3                              4





log(n)                   Logging facility                  log(n)


              was specified.

       ::log::loghex level text data
              Like  ::log::log, but assumes that data contains binary data. It
              converts this into a mixed hex/ascii representation before writ-
              ing them to the log.

       ::log::logMsg text
              Convenience wrapper around ::log::log.  Equivalent to ::log::log
              info text.

       ::log::logError text
              Convenience wrapper around ::log::log.  Equivalent to ::log::log
              error text.

       ::log::Puts level text
              The standard log command, it writes messages and their levels to
              user-specified channels. Assumes  that  the  suppression  checks
              were done by the caller. Expects full level names, abbreviations
              are not allowed.


LEVELS
       The package currently defines the following log levels,  the  level  of
       highest importance listed first.

       o      emergency

       o      alert

       o      critical

       o      error

       o      warning

       o      notice

       o      info

       o      debug

       Note that by default all messages with levels warning down to debug are
       suppressed. This is done intentionally, because (we  believe  that)  in
       most  situations  debugging  output  is not wanted. Most people wish to
       have such output only when actually debugging an application.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will  undoubtedly  contain
       bugs and other problems.  Please report such in the category log of the
       Tcllib  SF  Trackers  [http://sourceforge.net/tracker/?group_id=12883].
       Please  also  report any ideas for enhancements you may have for either
       package and/or documentation.




log                            1.3                              5





log(n)                   Logging facility                  log(n)


KEYWORDS
       log, log level, message, message level

CATEGORY
       Programming tools

COPYRIGHT
       Copyright (c) 2001-2009 Andreas Kupries <andreas_kupries@users.sourceforge.net>

















































log                            1.3                              6


