NormalLoggingApi - p36-log Wiki - p36-log

Normal Logging API

The Normal Logging API differentiates between "normal" log messages and "debug" log messages. This gives you two separate streams to write logging messages to. It also allows you to save all messages (normal and debug) to a set of other streams. This will let you, for example, save all the messages to a file as well as output them to the console.

Types

• T/LOG-LEVEL: Equivalent to (UNSIGNED-BYTE 8).

Globals

These are the various special variables that will influence how the Normal Logging API functions.

• *LOG-LEVEL*: The minimum level required to log messages. This can be any number of type T/LOG-LEVEL.

• *debug-LEVEL*: The minimum level required to log a debug message. This can be any number of type T/LOG-LEVEL.

• *LOG-STREAM*: The main stream to log messages to. Default is *STANDARD-OUTPUT*.

• *DEBUG-STREAM*: The main stream to log debugging messages to. Default is *ERROR-OUTPUT*.

• *MORE-LOG-STREAMS*: A list of additional streams to write normal and debug log messages to.

• *DEFAULT-HEADER*: When no header is specified in a normal logging function, this one will be displayed instead.

• *DEBUG-HEADER*: The default header for debug logging. This is always output.

• *FORCE-OUTPUT*: When non-NIL, FORCE-OUTPUT will be called after each logging call (though it can still be controlled with the lower-level function LOG/BASE). NOTE: this also affects the SimpleLoggingApi.

Normal Logging Functions/Macros

[Function]
LOG/BASE min-level header stream force-output dont-output-to-extras msg _&rest fmt-args

Low-level logging function. The output message is constructed so that HEADER appears first in brackets, followed by a colon and space, and then MSG, FORMATted with FMT-ARGS. In other words, the output format is such:

[header]: <formatted message>

Alternatively, if HEADER is an empty string, no header is output at all. Thus the output format is just:

<formatted output>

This message is only printed to STREAM if MIN-LEVEL is less than or equal to LOG-LEVEL, or FORCE-OUTPUT is non-NIL. Otherwise, nothing is printed.

If something is output to the primary stream, and DONT-OUTPUT-TO-EXTRAS is NIL, the formatted message is also printed to all extra streams defined in MORE-LOG-STREAMS.

[Macro]
WITH-LOGGING/BASE ’’(log-output-var min-level header stream force-output dont-output-to-extras) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls LOG/BASE with the the finished string. Returns a string when finished.

[Macro]
LOG (min-level _&optional header) msg _&rest fmt-args

Logs a message to the log stream and all extra log streams, except if MIN-LEVEL is greater than the current LOG-LEVEL. If MIN-LEVEL is higher than LOG-LEVEL, nothing is actually written to any log stream.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
FLOG (_&optional header) msg _&rest fmt-args

Logs a message to the log stream and all extra log streams. This ignores LOG-LEVEL, and thus always outputs something.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
LOG/NO-EXTRAS (min-level _&optional header) msg _&rest fmt-args

Logs a message to the main log stream, but does not output anything to any extra log stream. However, if MIN-LEVEL is greater than the current LOG-LEVEL, nothing is actually written to any log stream and this effectively does nothing.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
FLOG/NO-EXTRAS (_&optional header) msg _&rest fmt-args

Logs a message to the main log stream, but does not output anything to any extra log stream. This ignores LOG-LEVEL, and thus always outputs something.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
WITH-LOGGING (log-output-var min-level _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls LOG/BASE with the the finished string.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
WITH-FLOGGING (log-output-var _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls LOG/BASE with the the finished string, forcing the output.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
WITH-LOGGING/NO-EXTRAS (log-output-var min-level _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls LOG/BASE with the the finished string, specifying that no extra streams should be written to.

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

[Macro]
WITH-FLOGGING (log-output-var _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls LOG/BASE with the the finished string, forcing the output to the main stream, but skipping output to extra streams

If HEADER is supplied and is an empty string, no header will be output at all. If HEADER is not supplied at all, it will default to *DEFAULT-HEADER*.

Debug Logging Functions/Macros

[Function]
DEBUG-LOG/BASE min-level header stream force-output dont-output-to-extras msg _&rest fmt-args

Low-level logging function. The output message is constructed so that HEADER appears first in brackets, followed by a colon and space, and then MSG, FORMATted with FMT-ARGS. In other words, the output format is such:

  [header]: <formatted message>

Alternatively, if HEADER is an empty string, no header is output at all. Thus the output format is just:

  <formatted output>

This message is only printed to STREAM if MIN-LEVEL is less than or equal to *DEBUG-LEVEL*, or FORCE-OUTPUT is non-NIL. Otherwise, nothing is printed. If something is output to the primary stream, and DONT-OUTPUT-TO-EXTRAS is NIL, the formatted message is also printed to all extra streams defined in *MORE-LOG-STREAMS*.

[Macro]
WITH-DEBUG-LOGGING/BASE (log-output-var min-level header stream force-output dont-output-to-extras) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls DEBUG-LOG/BASE with the the finished string. Returns a string when finished.

[Macro]
DEBUG-LOG (min-level _&optional header) msg _&rest fmt-args

Logs a message to the log stream and all extra log streams, except if MIN-LEVEL is greater than the current {{{DEBUG-LOG-LEVEL}}}. If MIN-LEVEL is higher than {{{DEBUG-LOG-LEVEL}}}, nothing is actually written to any log stream. The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
DEBUG-FLOG (_&optional header) msg _&rest fmt-args

Logs a message to the log stream and all extra log streams. This ignores {{{DEBUG-LOG-LEVEL}}}, and thus always outputs something.

The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
DEBUG-LOG/NO-EXTRAS (min-level _&optional header) msg _&rest fmt-args

Logs a message to the main log stream, but does not output anything to any extra log stream. However, if MIN-LEVEL is greater than the current {{{LOG-LEVEL}}}, nothing is actually written to any log stream and this effectly does nothing. The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
DEBUG-FLOG/NO-EXTRAS (_&optional header) msg _&rest fmt-args

Logs a message to the main log stream, but does not output anything to any extra log stream. This ignores {{{DEBUG-LOG-LEVEL}}}, and thus always outputs something. The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
WITH-DEBUG-LOGGING (log-output-var min-level _&optional (header \*default-header\*)) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls DEBUG-LOG/BASE with the the finished string.

The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
WITH-DEBUG-FLOGGING (log-output-var _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls DEBUG-LOG/BASE with the the finished string, forcing the output.

The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
WITH-DEBUG-LOGGING/NO-EXTRAS (log-output-var min-level _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls DEBUG-LOG/BASE with the the finished string, specifying that no extra streams should be written to.

The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>

[Macro]
WITH-DEBUG-FLOGGING (log-output-var _&optional header) _&body forms

Binds LOG-OUTPUT-VAR to a string stream that you can write to in FORMS, then calls DEBUG-LOG/BASE with the the finished string, forcing the output to the main stream, but skipping output to extra streams.

The default header is always the same as {{{DEBUG-HEADER}}}. If you would like to prepend an extra header, you must supply EXTRA-HEADER. The header format will then be as such:

  [extraheader-DEBUGHEADER]: <formatted message>