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.8?

       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 seperated with '::'.
	      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 seperately 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 log-
	      ger::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 com-
	      plaining.  If the -prefix option is given, the commands are imported with the given prefix prepended to their names.  If the -names-
	      pace 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 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, 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  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 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  pack-
	      age.   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:

	      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 arguments to the procedure paired with values given for those arguments
		     (enter traces only).

	      o      status - The Tcl return code (e.g. ok, continue, etc.) (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  regis-
	      tered 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 ser-
	      vice.

       ${log}::trace command
	      This command controls logging of enter/leave traces for specified procedures.  It is used to enable and disable tracing, query trac-
	      ing  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 regis-
	      tering them for tracing through the trace add command.  Any procedure or namespace names/patterns that don't match any existing pro-
	      cedures 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  ::log-
       ger::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 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.

KEYWORDS

       log, log level, logger, service

log									0.8								 logger(n)