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}::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
'::'. 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.
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.
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.)
(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"
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
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
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 logger(n)
Mac OS X 10.8 - Generated Sun Sep 9 13:45:01 CDT 2012