Documentation for the functions in logging.sh. A general overview is given in the project 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$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 onstdout
, 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
If the pipes are not documented, the default is:
stdin
: ignoredstdout
: empty
Parameters enclosed in brackets [ ] are optional.
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:
| |
Pipes | stdout | depending on the configuration, the message for the console |
Status | 0 | |
Globals | all globals listed in the module documentation |
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
|
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 |