9.17 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 can also takes care of locking of the file (see the description of lock-policy below).

Class: <log-drain> ¶

{gauche.logger} 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 of <log-drain>: path ¶

Designates destination of log output. It can be one of the following values.

string

Pathname of the log file. The output is written to it.

current-error

#t

The output goes to the current error port.

current-output

The output goes to the current output port.

syslog

The output is sent to the system logger.

ignore

Make log-format does nothing.

#f

The output is turned to a string and returned from log-format.

By default, this slot is #f.

Instance Variable of <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.

~T

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.

~Y

Current 4-digit year.

~P

The program name. The default value is the basename of (car (command-line)) (see Command-line arguments), but you can change it by the program-name slot described below.

~$

The process id of this program.

~U

The name of the effective user of the process.

~H

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 of <log-drain>: program-name ¶

Specifies the program name written by ~P directive of the prefix slot.

Instance Variable of <log-drain>: lock-policy ¶

Specifies the way the log file should be locked. If the value of this slot is a symbol fcntl, the log file is locked using fcntl() (see gauche.fcntl - Low-level file operations). If the value is a symbol file, the log file is locked by creating auxiliary lock file, whose name is generated by appending ".lock" after the log file path. The logging process needs a write permission to the log file directory. Note that if the process is killed forcibly during writing the log file, a stale lock file may remain. Log-format silently removes the lock file if it is unusually old (currently 10 minutes). If the value is #f, no locking is performed.

The default value is fcntl, except MacOSX which doesn’t support fcntl()-style locking and thus file is default.

The locking isn’t performed if the destination is not a file.

Instance Variable of <log-drain>: syslog-option ¶

Instance Variable of <log-drain>: syslog-facility ¶

Instance Variable of <log-drain>: syslog-priority ¶

The value of these slots are used when the destination of the drain is the system logger. See 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 :key prefix program-name ¶

{gauche.logger} 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. See the <log-drain> above for those parameters.

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

Parameter: log-default-drain ¶

{gauche.logger} When called with no argument, returns the current default log-drain log-format uses when the explicit drain is omitted. It may return #f if the default log drain hasn’t been opened by log-open.

Calling with new <log-drain> object or #f alters the default log-drain. You can also use parameterize (Parameters) to change the log drain temporary.

Method: log-format (format <string>) arg … ¶

Method: log-format (drain <log-drain>) (format <string>) arg … ¶

{gauche.logger} Formats a log message by format and arg …, by using format (see Output). In the first form, the output goes to the default destination. In the second form, the output goes to the specified 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 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.