14.5 Logging
A logger accepts events that contain information to be logged for interested parties. A log receiver represents an interested party that receives logged events asynchronously. Each event has a level of importance, and a log receiver subscribes to logging events at a certain level of importance and higher. The levels, in decreasing order of importance, are 'fatal, 'error, 'warning, 'info, and 'debug.
To help organize logged events, loggers can be named and hierarchical. Every event reported to a logger is also propagated to its parent (if any), but the event message is prefixed with the name (if any) of the logger to which is was originally reported. A logger is not required to have a parent or name.
On start-up, Racket creates an initial logger that is used to record events from the core run-time system. For example, an 'info event is reported for each garbage collection (see Garbage Collection). For this initial logger, two log receivers are also created: one that writes events to the process’s original error output port, and one that writes events to the system log. The level of written events in each case is system-specific, and the default can be changed through command-line flags (see Command Line) or through environment variables:
If the PLTSTDERR environment variable is defined and is not overridden by a command-line flag, it determines the level of the log receiver that propagates events to the original error port. The environment variable’s value should be "none", "fatal", "error", "warning", "info", or "debug".
The default is "error".
If the PLTSYSLOG environment variable is defined and is not overridden by a command-line flag, it determines the level of the log receiver that propagates events to the system log. The possible values are the same as for PLTSYSLOG.
The default is "none" for Unix or "error" for Windows and Mac OS X.
The current-logger parameter determines the current logger that is used by forms such as log-warning. On start-up, the initial value of this parameter is the initial logger. The run-time system sometimes uses the current logger to report events. For example, the bytecode compiler sometimes reports 'warning events when it detects an expression that would produce a run-time error if evaluated.
14.5.1 Creating Loggers
(logger-name logger) → (or/c symbol? #f) logger : logger?
(current-logger) → logger? (current-logger logger) → void? logger : logger?
14.5.2 Logging Events
(log-message logger level message data) → void? logger : logger? level : (or/c 'fatal 'error 'warning 'info 'debug) message : string? data : any/c
If logger has a name, then message is prefixed with the logger’s name followed by ": " before it is sent to receivers.
(log-level? logger level) → boolean? logger : logger? level : (or/c 'fatal 'error 'warning 'info 'debug)
The result of this function can change if a garbage collection determines that a log receiver is no longer accessible (and therefore that any event information it receives will never become accessible).
(log-fatal string-expr)
(log-error string-expr)
(log-warning string-expr)
(log-info string-expr)
(log-debug string-expr)
For each log-level,
(log-level string-expr)
is equivalent to
(let ([l (current-logger)]) (when (log-level? l 'level) (log-message l 'level string-expr (current-continuation-marks))))
14.5.3 Receiving Logged Events
(log-receiver? v) → boolean? v : any/c
(make-log-receiver logger level) → log-receiver? logger : logger? level : (or/c 'fatal 'error 'warning 'info 'debug)
A log receiver is a synchronizable event. It becomes ready as an synchronizable event when a logging event is received, so use sync to receive an logged event. The log receiver’s synchronization value is a vector containing three values: the level of the event as a symbol, an immutable string for the event message, and an arbitrary value that was supplied as the last argument to log-message when the event was logged.