logging.md

Documentation for the functions in logging.sh. A general overview is given in the project documentation.

Module documentation

The logging module provides stdout and file logging at once, each with a individual pattern and log level. These levels follow a verbosity logic where a message with a lower level should be more important than one with a higher level. Through a configuration flag, the logger may be put in a "delayed logging" mode where the messages go into a buffer for a processing later on. That's useful when an application wants to start to use the logger before the logging configuration is fully determined.

Since all these configurations have to persist between the log() calls, the module relies on global variables:

• $logging_available: the "delayed logging" flag
  • if it's defined and set to 0, log() copies messages to $logging_backlog, the buffer
  • if it's undefined or set to 1, log() processes the messages immediately
• $stdout_log_level: defines the stdout channel verbosity filter threshold. Messages with a level above the threshold are discarded. If the variable is undefined, not numeric or 0, nothing is written
• $stdout_log_pattern: pattern of the message written on stdout, where a single %s represents the message. If the variable is undefined, %s is used (i.e. "just the message")
• $log_filepath: absolute path of the logfile. If the variable is undefined or empty, no file logging occurs
• $log_level: defines the file logging channel verbosity filter threshold. Messages with a level above the threshold are discarded. If the variable is undefined, not numeric or 0, no file logging occurs
• $log_pattern: pattern of the message written to the logfile, where a single %s represents the message. If the variable is undefined, %s is used (i.e. "just the message")
• $logging_backlog array: buffer for messages when $logging_available is set to 0. Handled internally between log() and launch_logging()

Example: sendmail2mailgun uses all module features

Function documentation

If the pipes are not documented, the default is:

• stdin: ignored
• stdout: empty

Parameters enclosed in brackets [ ] are optional.

log()

The central piece of the module. Supports prefix-aware multi-line output and independent stdout and file output handling. Copies messages to the $logging_backlog as long as $logging_available is set to 0. See the module documentation for details.

Important: always call this function and launch_logging() directly on global level and not through $(...), otherwise the global variables don't work (a subshell receives a copy of the parent shell's variable set and has no access to the "original" ones).

Param.	$1	message to log
	[$2]	log level - if omitted, it defaults to 1
	[$3]	output channel restriction: if omitted, both stdout and file logging are addressed file: file logging only stdout: stdout logging only This configuration selects the addressed output channel(s) but it does not overwrite the configurations which define whether logging actually occurs (see module documentation)
Pipes	stdout	depending on the configuration, the message for the console
Status	0
Globals		all globals listed in the module documentation

launch_logging()

Processes the $logging_backlog by calling log() for each entry. Before returning, it clears that backlog and sets $logging_available to 1.

Pipes	stdout	if stdout logging is enabled, the logs for stdout, empty otherwise
Status	0
Globals		- $logging_available - $logging_backlog

prepare_secret_for_logging()

Formats a secret for logging. The amount of characters can be configured through $2 and the security factor $3 (a value between 0 and 1) which guarantees that the amount shown is at most <secret length> * <factor>. If $2 is negative, the characters are shown from the end of the secret, if it's positive, from the beginning. The message pattern is [Secret - begins with ...] respectively [Secret - ends with ...]. Examples:

prepare_secret_for_logging "longer_secret" 5 "0.5"

writes [Secret - begins with 'longe'] on stdout. In this case the security factor doesn't intervene because 0.5 * 13 = 6.5, $2 is lower. The default security factor is 0.25. Example with a negative $2:

test prepare_secret_for_logging "longer_secret" -5

writes [Secret - ends with 'ret'] on stdout. It contains only 3 instead of the 5 characters requested because the default security factor sets the limit to 13*0.25=3.25.

Param.	$1	secret
	[$2]	amount of charcters to show. If it's positive, the amount is shown from the beginning of the secret, if it's negative, from the end. If it's omitted, the first fourth of the secret will be shown.
	[$3]	security factor: a value between 0 and 1 which configures how much of the secret can be shown at most. Defaults to 0.25, which means that by default at most one fourth of the secret's characters will be shown. It's enforced as limit for the amount of characters which can be requested via $2
Pipes	stdout	if status is 0, a representation of the secret suited for logging, empty otherwise
Status	0	success, the formatted secret was written on `stdout`
	1	$1 undefined or empty