|
ActiveTcl User Guide
|
|
|
[ Main table Of Contents | Tcllib Table Of Contents | Tcllib Index ]
logger(n) 0.5 "Object Oriented logging facility"
logger - System to control logging of events.
TABLE OF
CONTENTS
SYNOPSIS
DESCRIPTION
IMPLEMENTATION
KEYWORDS
package require Tcl 8.2
package require logger ?0.5?
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.
- 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::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.
- 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.
- 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
- 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 critical switches
logging off for the service and its children.
- ${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
|
- ${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.
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.
log , log level , logger , service