[ Table Of Contents | Index ]

logger(n) 0.1.0 "Object Oriented logging facility"

NAME

logger - System to control logging of events.

SYNOPSIS

package require Tcl 8
package require logger ?0.1.0?

logger::init service
logger::services
logger::enable level
logger::disable level
${log}::debug message
${log}::info message
${log}::notice message
${log}::warn message
${log}::error message
${log}::critical message
${log}::setlevel level
${log}::enable level
${log}::disable level
${log}::logproc level argname body
${log}::services
${log}::delete

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}::destroy

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 initalized, 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.

logger::services
Returns a list of all the available services.

logger::enable level
Globally enables logging at or "above" the given level. Levels are debug, info, notice, warn, error, critical.

logger::disable level
Globally disables logging at or "below" the given level. Levels are those listed above.

${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 or above the level specified, and disable logging below it.

${log}::enable level
Enable logging, in the service referenced by ${log}, and its children, at or 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 or below the level specified. Note that this does not enable logging above this level, so you should probably use setlevel instead.

${log}::logproc level argname body
This is a command to define a command that 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:

 
    ${log}::logproc notice txt {
	puts $netlog "Notice: $txt"
    }



${log}::services
Returns a list of all the registered logging services.

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

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.

KEYWORDS

log , log level , logger , service