


logger(n)        Object Oriented logging facility       logger(n)


______________________________________________________________________________

NAME
       logger - System to control logging of events.

SYNOPSIS
       package require Tcl  8.2

       package require logger  ?0.9?

       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                            0.8                              1





logger(n)        Object Oriented logging facility       logger(n)


       ${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



log                            0.8                              2





logger(n)        Object Oriented logging facility       logger(n)


       happen:

       logger::init service
              Initializes the service service for logging.  The service  names
              are  actually  Tcl  namespace  names, so they are separated with
              '::'.  When a logger service is initialized, it "inherits" prop-
              erties  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 initial-
              ized and the parent does not yet exist, the parent is also  cre-
              ated.   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 com-
              mands 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. Cre-
              ates  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 to the specified
              level, or the default level, "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, emer-
              gency.

       logger::disable level
              Globally disables logging at and "below" the given level.   Lev-
              els 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.



log                            0.8                              3





logger(n)        Object Oriented logging facility       logger(n)


       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  ser-
              vice.

       ${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  cur-
              rently  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  call-
              back.



log                            0.8                              4





logger(n)        Object Oriented logging facility       logger(n)


                   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 dep-
              recated 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 argu-
              ment,  the argument provided to the logproc is a dictionary con-
              sisting of the enter or leave keyword along with another dictio-
              nary of details about the trace.  These include:

              o      proc - Name of the procedure being traced.

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

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

              o      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).

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

              o      status - The Tcl return code (e.g.  ok,  continue,  etc.)



log                            0.8                              5





logger(n)        Object Oriented logging facility       logger(n)


                     (leave traces only).

              o      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 chil-
              dren.   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  speci-
              fied  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  trac-
              ing 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"



log                            0.8                              6





logger(n)        Object Oriented logging facility       logger(n)


                    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 com-
              mand will return an error if called  from  earlier  versions  of
              Tcl.

       ${log}::trace off
              Turns off trace logging for procedures registered for trace log-
              ging through the trace add command.  This is similar to the dis-
              able  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 com-
              mand.  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 regis-
              tered 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 interpreta-
              tion 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/pat-
              terns  that don't match any existing procedures will be silently



log                            0.8                              7





logger(n)        Object Oriented logging facility       logger(n)


              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 ::log-
       ger::tree::myservice::warn), so that no variable lookup is done.   This
       puts  the performance of disabled logger commands very close to no log-
       ging 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



log                            0.8                              8





logger(n)        Object Oriented logging facility       logger(n)


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         SF         Trackers         [http://source-
       forge.net/tracker/?group_id=12883].  Please also report any  ideas  for
       enhancements you may have for either package and/or documentation.

KEYWORDS
       log, log level, logger, service

CATEGORY
       Programming tools













































log                            0.8                              9


