Logging

This module implements a set of functions for logging messages either to a console or to a file. Every message has a category that acts as a searchable hierarchical tag, and optional parameters that will be substituted into the message by replacing placeholders {1}, {2}, etc. Output have the following format:

[<timestamp>][<category>][<level>] <message after substitutions>

For example,

# [2021-10-05T23:15:08][test][INFO] The path 'examples' will be used
log_info(test "The path '{1}' will be used" examples)
# send log messages in `test` to the file `test.log`
log_to_file(test test.log)
# message appended to test.log
log_warn(test "ICU not found")
# enable debug messages
log_level(test DEBUG)
# printed as well - categories maintain parent-child relation
log_info(test.nested "This message should be logged, too.")

Notice the parameter examples after the main message in the example above. Use of parameters is entirely optional; they are only for readability.

When to use

Controlled logging is useful in debugging, when it’s easy to add a lot of calls to message and it’s hard to remove them afterwards. This is not needed with this module - just raise the logging level of the corresponding category with either a call to log_level or via

-Dlog.context.<<context name>>.level=ERROR

Functions

log_message

log_message(_level _category _message)

Formats and prints the given message. Filters out the messages based on the logging level of the category _category, previously specified by a call to log_level.

log_level

log_level(_category _level)

All the subsequent messages in the given category _category and its nested categories will only be printed if their level is at least as high as _level. The levels are defined by the function _log_levels (the further it is from the beginning, the higher it is). The default level for every category is WARN.

log_to_file

log_to_file(_category _file_name)

Redirects all subsequent logged messages in the category _category and its nested categories to a file _file_name instead of the console.

log_to_console

log_to_console(_category)

Directs all subsequent logged messages in the category _category to the console instead of a file, previously specified by a call to log_to_file. Does nothing if the message redirection was not requested for the given category.

log_debug

log_debug(_category _message <message arguments>)

Formats the given message and prints it either to a console or to a file. The messages have the following format: [<<timestamp>>][<<category>>][DEBUG] <<message after substitutions>>> This function is a wrapper around log_message.

log_trace

log_trace(_category _message <message arguments>)

Formats the given message and prints it either to a console or to a file. The messages have the following format: [<<timestamp>>][<<category>>][TRACE] <<message after substitutions>>> This function is a wrapper around log_message.

log_info

log_info(_category _message <message arguments>)

Calls log_message with the level set to INFO.

log_error

log_error(_category _message <message arguments>)

Calls log_message with the level set to ERROR.

log_warn

log_warn(_category _message <message arguments>)

Calls log_message with the level set to FATAL.

log_warn

log_warn(_category _message <message arguments>)

Calls log_message with the level set to WARN.