Provided by: tcllib_1.15-dfsg-2_all 
NAME
logger - System to control logging of events.
SYNOPSIS
package require Tcl 8.2
package require logger ?0.9.3?
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"
${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 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 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 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
CATEGORY
Programming tools