[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

9.8 gauche.logger - User-level logging

Module: gauche.logger
Provides a simple interface to log the program's activity. The information can be written to the specified file, or to the system logger using syslog(3). When a file is used, syslog-like prefix string is added to each message, which is configurable. It also takes care of locking of the file.

Class: <log-drain>
Represents the destination of log messages. There's one implicit global <log-drain> instance, which is used by default. However, you can create as many instances by make method as you want, in case if you want to log to more than one destination.

Instance Variable: <log-drain> path
Path of the log file. It can be also #t, which means the current error port, or #f, which makes log-format to return the formatted message but not write to any log files, or a symbol syslog, which means the messages are sent to the system logger.

By default, this slot is #f.

Instance Variable: <log-drain> prefix
Specifies the prefix string that is attached to the beginning of every message. If the message spans to several lines, the prefix is attached to each line. The value of this slot can also be a procedure that takes <log-drain> object and returns a string to be used as the prefix. The procedure is called every time prefix is needed.

When the path slot is a symbol syslog, the value of this slot is ignored. System logger will attach an appropriate prefix.

When the value of the prefix slot is a string, the following character sequences have special meanings and replaced by log-format for appropriate information when written out.

Current time, in the format of "Mmm DD hh:mm:ss" where "Mmm" is an abbreviated month, "DD" is the day of month, "hh", "mm" and "ss" are hours (in 24 hour basis), minutes and seconds, respectively. This format is compatible with system logs.

Current 4-digit year.

The program name. The default value is the basename of *program-name* (See section 3.4 Writing Scheme scripts), but you can change it by the program-name slot described below.

The process id of this program.

The name of the effective user of the process.

The hostname the process is running.

The default value of this slot is "~T ~P[~$]: ". For example, if a string "this is a log message.\nline 2\nline 3" is given as the message, it produces something like the following log entry.

Sep  1 17:30:23 myprogram[441]: this is a log message
Sep  1 17:30:23 myprogram[441]: line 2
Sep  1 17:30:23 myprogram[441]: line 3

Instance Variable: <log-drain> program-name
Specifies the program name written by ~P directive of the prefix slot.

Instance Variable: <log-drain> syslog-option
Instance Variable: <log-drain> syslog-facility
Instance Variable: <log-drain> syslog-priority
The value of these slots are used when the destination of the drain is the system logger. See section 9.19 gauche.syslog - Syslog, for the detailed information about these values. The default values of these slots are LOG_PID, LOG_USER and LOG_INFO, respectively.

Function: log-open path &keyword prefix program-name
Sets the destination of the default log message to the path path. It can be a string or a boolean, as described above. You can also set prefix and program name by corresponding keyword arguments.

Despite its name, this function doesn't open the specified file immediately. The file is opened and closed every time log-format is called.

Method: log-format (format <string>) arg ...
Method: log-format (drain <log-drain>) (format <string>) arg ...
Formats a log message by format and arg ..., by using format (See section 6.18.7 Output). In the first form, the output goes to the default destination. In the second form, the output goes to the specfied drain.

The file is opened and closed every time. You can safely move the log file while your program that touches the log file is running. Also log-format acquires a write lock of the log file by sys-fcntl (See section 9.5 gauche.fcntl - Low-level file operations).

If the first form of log-format is called before log-open is called, log-format does nothing. It is useful to embed debug stubs in your code; once your code is past the debugging stage, you just comment out log-open and the code runs without logging.

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

This document was generated by Ken Dickey on November, 28 2002 using texi2html