Logging
Prev   Next

Logging

Logging consists of two parts. web::log issues a logging message, while web::loglevel and web::logdest determine where to send a message. Websh uses a two-step filtering. First, Websh determines whether it should handle a message, or not, using the levels configured with web::loglevel. Then, Websh determines which message is to be sent where, using the the additional filters and destinations configured with web::logdest. There is no logging per default. Setting levels with web::loglevel is mandatory.

A filter consists of a tag and a level, separated by a ".". The tag is free text. Typically, it is the name of the application, say "foo". Example: "ws3.debug". Levels are, in order:

web::logdest

web::logdest subcommand ?options? args

Subcommands are: add, delete, names, and levels.

web::logdest add ?options? level plugin ?plugin-specific options?
Options are: -maxchar n, and -format "format string". -maxchar n truncates the message to a maximum of n characters.
The format string consists of time format specifications for strftime() plus: $p (process id), $t (thread id), $l (log level), $n (numerical log level), $f (log facility), $m (the message), $U (microseconds), $M (milliseconds), and $$ (dollar sign). strftime() format string for ISO8601 datetime is "%F %T" equivalent to "%Y-%m-%d %H:%M:%S".
Default format is "%x %X [\$p] \$f.\$l: \$m\n"
Known plug-ins are: file, syslog (Unix only), command, channel, and apache (mod_websh only). Note: plugins may have indiviudal options (-unbuffered), see documentation below. 
web::logdest add -maxchar 32 -format "%F %T.\$M \$l \$m\n" *.-debug command logTest
web::logdest delete ?name?
remove destination name from list, or remove all destinations if name is omitted. (The special case -requests to delete all destinations except the one defined from within web::initializer code is only used internally.)
web::logdest names
return a list of all destination ids that have been set.
web::loglevel levels
list all destination ids and their actual log levels in a readable format

web::loglevel

web::loglevel subcommand args

Subcommands are: add, delete, names, and levels. Levels defined using web::loglevel act as a filter for log messages sent by Websh. Only messages that pass at least one level defined using this command are passed to the log destinations configured using web::logdest

web::loglevel add level
add a level to the list.
web::loglevel delete ?name?
remove level name from list, or remove all levels if name is omitted. (The special case -requests to delete all levels except the one defined from within web::initializer code is only used internally.)
web::loglevel names
return a list of all level ids that have been set.
web::loglevel levels
list all level ids and their actual log levels in a readable format

web::log

web::log level msg

Issue a log message. It is possible, should the user so desire, to have the web::log run subst on its arguments. This behaviour is turned off by default, and can be turned on by doing: 

web::config logsubst 1

.

Log plug-ins

File

web::logdest add destination.-level file ?options? filename

Option is: -unbuffered

Log messages are sent to the file filename, which is opened in append mode at the time of this call and stays open until this destination is deleted. This is either at the end of the request (mod_websh) or when the interpreter is deleted.

The file opened using the permissions configured with web::config filepermissions. Default is 0644.

Syslog

web::logdest add *.-debug syslog ?level?

See the man page for syslog for levels on your system. Typical: 10. Available under Unix only.

Command

web::logdest add *.-debug command cmdName

The log message is sent to a Tcl command taking the message as an argument. E.g. 

% proc logCommand {msg} {
      puts "---- here comes the message ----"
      puts -nonewline $msg
      puts "----- that was the message -----"
}
%
% web::loglevel add *.-debug
loglevel0
% web::logdest add *.-debug command logCommand
logdest0
% web::log debug " a log message"
---- here comes the message ----
10/28/05 13:44:26 [20596] user.debug:  a log message
----- that was the message -----
%

Channel

web::logdest add *.-debug channel ?options? channel

Option is: -unbuffered

Write the message to the Tcl channel channel.

Apache

web::logdest add *.-debug apache

Sends the message to the Apache ErrorLog file. Available in mod_websh only.

Example 11. web::log

% web::loglevel add *.-debug
loglevel0
% web::logdest add *.-debug channel stdout
logdest0
% web::log info {Websh is cool}
03/01/00 00:00:00 [111] user.info: Websh is cool
% web::logdest delete
% web::logdest add -format "--> \$m\n" *.-debug channel stdout
logdest0
% web::log info {Websh is cool}
--> Websh is cool
% web::logdest delete
% web::logdest add -maxchar 5 *.-debug channel stdout
% web::log info {Websh is cool}
03/01/00 00:00:00 [111] user.info: Websh
%

Prev   Next
Response data handling Home Context handling