Provided by: tcllib_1.19-dfsg-2_all bug

NAME

       logger - System to control logging of events.

SYNOPSIS

       package require Tcl  8.2

       package require logger  ?0.9.4?

       logger::init service

       logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service

       logger::initNamespace ns ?level?

       logger::services

       logger::enable level

       logger::disable level

       logger::setlevel level

       logger::levels

       logger::servicecmd service

       ${log}::debug message

       ${log}::info message

       ${log}::notice message

       ${log}::warn message

       ${log}::error message

       ${log}::critical message

       ${log}::alert message

       ${log}::emergency message

       ${log}::setlevel level

       ${log}::enable level

       ${log}::disable level

       ${log}::lvlchangeproc command

       ${log}::lvlchangeproc

       ${log}::logproc level

       ${log}::logproc level command

       ${log}::logproc level argname body

       ${log}::services

       ${log}::servicename

       ${log}::currentloglevel

       ${log}::delproc command

       ${log}::delproc

       ${log}::delete

       ${log}::trace command

       ${log}::trace on

       ${log}::trace off

       ${log}::trace status ?procName? ?...?

       ${log}::trace add procName ?...?

       ${log}::trace add ?-ns? nsName ?...?

       ${log}::trace remove procName ?...?

       ${log}::trace remove ?-ns? nsName ?...?

_________________________________________________________________________________________________

DESCRIPTION

       The  logger  package  provides  a  flexible  system  for  logging  messages from different
       services, at priority levels, with different commands.

       To begin using the logger package, we do the following:

                  package require logger
                  set log [logger::init myservice]
                  ${log}::notice "Initialized myservice logging"

                  ... code ...

                  ${log}::notice "Ending myservice logging"
                  ${log}::delete

       In the above code, after the package is loaded, the following things happen:

       logger::init service
              Initializes the service service for logging.  The service names  are  actually  Tcl
              namespace  names, so they are separated with '::'.  The service name may not be the
              empty string or only ':'s.  When a logger service  is  initialized,  it  "inherits"
              properties from its parents.  For instance, if there were a service foo, and we did
              a logger::init foo::bar (to create a bar service underneath foo),  bar  would  copy
              the  current configuration of the foo service, although it would of course, also be
              possible to then separately configure bar.  If a logger service is initialized  and
              the  parent does not yet exist, the parent is also created.  The new logger service
              is initialized with the default loglevel set with logger::setlevel.

       logger::import ?-all? ?-force? ?-prefix prefix? ?-namespace namespace? service
              Import the logger service commands into the current  namespace.  Without  the  -all
              option  only  the commands corresponding to the log levels are imported. If -all is
              given, all the ${log}::cmd  style  commands  are  imported.  If  the  import  would
              overwrite a command an error is returned and no command is imported. Use the -force
              option to force the import and overwrite existing commands without complaining.  If
              the  -prefix  option  is  given,  the  commands  are imported with the given prefix
              prepended to their names.  If the -namespace option  is  given,  the  commands  are
              imported  into the given namespace. If the namespace does not exist, it is created.
              If a namespace without a leading  ::  is  given,  it  is  interpreted  as  a  child
              namespace to the current namespace.

       logger::initNamespace ns ?level?
              Convenience  command  for  setting  up  a  namespace  for logging. Creates a logger
              service named after the namespace ns (a :: prefix is stripped), imports all the log
              commands  into  the  namespace,  and  sets  the  default  logging  level, either as
              specified by level, or inherited from a service  in  the  parent  namespace,  or  a
              hardwired default, warn.

       logger::services
              Returns a list of all the available services.

       logger::enable level
              Globally  enables  logging at and "above" the given level.  Levels are debug, info,
              notice, warn, error, critical, alert, emergency.

       logger::disable level
              Globally disables logging at and "below" the given level.  Levels are those  listed
              above.

       logger::setlevel level
              Globally  enable  logging  at  and "above" the given level. Levels are those listed
              above. This command changes the default  loglevel  for  new  loggers  created  with
              logger::init.

       logger::levels
              Returns a list of the available log levels (also listed above under enable).

       logger::servicecmd service
              Returns the ${log} token created by logger::init for this service.

       ${log}::debug message

       ${log}::info message

       ${log}::notice message

       ${log}::warn message

       ${log}::error message

       ${log}::critical message

       ${log}::alert message

       ${log}::emergency message
              These  are the commands called to actually log a message about an event.  ${log} is
              the variable obtained from logger::init.

       ${log}::setlevel level
              Enable logging, in the service referenced by ${log}, and its children, at and above
              the level specified, and disable logging below it.

       ${log}::enable level
              Enable logging, in the service referenced by ${log}, and its children, at and above
              the level specified.  Note that this does not disable logging below this level,  so
              you should probably use setlevel instead.

       ${log}::disable level
              Disable  logging,  in  the  service  referenced by ${log}, and its children, at and
              below the level specified. Note that this does not enable logging above this level,
              so  you  should  probably  use  setlevel instead.  Disabling the loglevel emergency
              switches logging off for the service and its children.

       ${log}::lvlchangeproc command

       ${log}::lvlchangeproc
              Set the script to call when the log instance in question changes its log level.  If
              called  without  a command it returns the currently registered command. The command
              gets two arguments appended, the old and the new loglevel. The callback is  invoked
              after  all  changes have been done.  If child loggers are affected, their callbacks
              are called before their parents callback.

                proc lvlcallback {old new} {
                    puts "Loglevel changed from $old to $new"
                }
                ${log}::lvlchangeproc lvlcallback

       ${log}::logproc level

       ${log}::logproc level command

       ${log}::logproc level argname body
              This command comes in three forms - the third, older one is deprecated and  may  be
              removed  from future versions of the logger package.  The current set version takes
              one argument, a command to be executed when the  level  is  called.   The  callback
              command takes on argument, the text to be logged. If called only with a valid level
              logproc returns the name of the command currently registered as  callback  command.
              logproc  specifies which command will perform the actual logging for a given level.
              The logger package ships with default commands for all log levels, but with logproc
              it is possible to replace them with custom code.  This would let you send your logs
              over the network, to a database, or anything else.  For example:

                  proc logtoserver {txt} {
                      variable socket
                      puts $socket "Notice: $txt"
                  }

                  ${log}::logproc notice logtoserver

              Trace logs are slightly different: instead of a plain text argument,  the  argument
              provided  to  the  logproc is a dictionary consisting of the enter or leave keyword
              along with another dictionary of details about the trace.  These include:

              •      proc - Name of the procedure being traced.

              •      level - The stack level for the procedure invocation (from info level).

              •      script - The name of the file in which the procedure is defined, or an empty
                     string if defined in interactive mode.

              •      caller - The name of the procedure calling the procedure being traced, or an
                     empty string if the procedure was called from the global scope (stack  level
                     0).

              •      procargs  -  A  dictionary  consisting  of  the  names  of  arguments to the
                     procedure paired with values given for those arguments (enter traces only).

              •      status - The Tcl return code (e.g. ok, continue, etc.) (leave traces only).

              •      result - The value returned by the procedure (leave traces only).

       ${log}::services
              Returns a list of the registered  logging  services  which  are  children  of  this
              service.

       ${log}::servicename
              Returns the name of this service.

       ${log}::currentloglevel
              Returns  the currently enabled log level for this service. If no logging is enabled
              returns none.

       ${log}::delproc command

       ${log}::delproc
              Set the script to call when the log instance in question  is  deleted.   If  called
              without a command it returns the currently registered command.  For example:

                  ${log}::delproc [list closesock $logsock]

       ${log}::delete
              This command deletes a particular logging service, and its children.  You must call
              this to clean up the resources used by a service.

       ${log}::trace command
              This command controls logging of enter/leave traces for specified  procedures.   It
              is used to enable and disable tracing, query tracing status, and specify procedures
              are to be traced.  Trace handlers are unregistered when tracing is disabled.  As  a
              result, there is not performance impact to a library when tracing is disabled, just
              as with other log level commands.

                proc tracecmd { dict } {
                    puts $dict
                }

                set log [::logger::init example]
                ${log}::logproc trace tracecmd

                proc foo { args } {
                    puts "In foo"
                    bar 1
                    return "foo_result"
                }

                proc bar { x } {
                    puts "In bar"
                    return "bar_result"
                }

                ${log}::trace add foo bar
                ${log}::trace on

                foo

              # Output:
              enter {proc ::foo level 1 script {} caller {} procargs {args {}}}
              In foo
              enter {proc ::bar level 2 script {} caller ::foo procargs {x 1}}
              In bar
              leave {proc ::bar level 2 script {} caller ::foo status ok result bar_result}
              leave {proc ::foo level 1 script {} caller {} status ok result foo_result}

       ${log}::trace on
              Turns on trace logging for procedures registered through  the  trace  add  command.
              This  is  similar  to the enable command for other logging levels, but allows trace
              logging to take place at any level.  The trace logging mechanism takes advantage of
              the execution trace feature of Tcl 8.4 and later.  The trace on command will return
              an error if called from earlier versions of Tcl.

       ${log}::trace off
              Turns off trace logging for procedures registered for  trace  logging  through  the
              trace  add  command.   This  is  similar  to  the disable command for other logging
              levels, but allows trace logging to take place at any level.   Procedures  are  not
              unregistered,  so logging for them can be turned back on with the trace on command.
              There is no overhead imposed by trace registration when trace logging is disabled.

       ${log}::trace status ?procName? ?...?
              This command returns a list  of  the  procedures  currently  registered  for  trace
              logging,  or a flag indicating whether or not a trace is registered for one or more
              specified procedures.

       ${log}::trace add procName ?...?

       ${log}::trace add ?-ns? nsName ?...?
              This command registers one or more procedures for  logging  of  entry/exit  traces.
              Procedures  can  be  specified via a list of procedure names or namespace names (in
              which case all procedure within the namespace are targeted by the  operation).   By
              default,  each  name  is first interpreted as a procedure name or glob-style search
              pattern, and if not found its interpreted as a namespace name.  The -ns option  can
              be  used  to  force  interpretation  of  all provided arguments as namespace names.
              Procedures must be defined prior to registering them for tracing through the  trace
              add  command.   Any  procedure  or  namespace  names/patterns  that don't match any
              existing procedures will be silently ignored.

       ${log}::trace remove procName ?...?

       ${log}::trace remove ?-ns? nsName ?...?
              This command unregisters one or more procedures so that they will  no  longer  have
              trace  logging  performed,  with  the  same matching rules as that of the trace add
              command.

IMPLEMENTATION

       The logger package is implemented in such a way as to optimize (for Tcl 8.4 and newer) log
       procedures  which  are  disabled.   They are aliased to a proc which has no body, which is
       compiled to a no op in bytecode.  This should make the peformance  hit  minimal.   If  you
       really  want to pull out all the stops, you can replace the ${log} token in your code with
       the actual namespace and command (${log}::warn  becomes  ::logger::tree::myservice::warn),
       so that no variable lookup is done.  This puts the performance of disabled logger commands
       very close to no logging at all.

       The "object orientation" is done through a  hierarchy  of  namespaces.   Using  an  actual
       object oriented system would probably be a better way of doing things, or at least provide
       for a cleaner implementation.

       The service "object orientation" is done with namespaces.

LOGPROCS AND CALLSTACK

       The logger package takes extra care to keep the logproc  out  of  the  call  stack.   This
       enables logprocs to execute code in the callers scope by using uplevel or linking to local
       variables by using upvar. This may fire traces with all usual side effects.

                   # Print caller and current vars in the calling proc
                   proc log_local_var {txt} {
                        set caller [info level -1]
                        set vars [uplevel 1 info vars]
                        foreach var [lsort $vars] {
                           if {[uplevel 1 [list array exists $var]] == 1} {
                           lappend val $var <Array>
                           } else {
                           lappend val $var [uplevel 1 [list set $var]]
                           }
                        }
                        puts "$txt"
                        puts "Caller: $caller"
                        puts "Variables in callers scope:"
                        foreach {var value} $val {
                        puts "$var = $value"
                        }
                   }

                   # install as logproc
                   ${log}::logproc debug log_local_var

BUGS, IDEAS, FEEDBACK

       This document, and the package it describes,  will  undoubtedly  contain  bugs  and  other
       problems.    Please   report   such   in  the  category  logger  of  the  Tcllib  Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

       When proposing code changes, please provide unified diffs, i.e the output of diff -u.

       Note further that attachments are strongly preferred over inlined patches. Attachments can
       be made by going to the Edit form of the ticket immediately after its creation,  and  then
       using the left-most button in the secondary navigation bar.

KEYWORDS

       log, log level, logger, service

CATEGORY

       Programming tools