The log module implements functions for logging and debugging with different log levels. A script that includes
this module has a global log level that defaults to __log_warning, meaning that by default only warnings and
errors will be logged. The log level may be adjusted to increase or decrease the amount of log messages.
| Log level | Meaning |
|---|---|
__log_debug |
Log everything |
__log_info |
Log errors, warnings, and informational messages |
__log_warning |
Log errors and warnings (default) |
__log_error |
Log only errors |
This module does not depend on other modules.
| Function | Purpose |
|---|---|
| log_debug() | Log a debug message |
| log_decrease_verbosity() | Decrease the log level |
| log_error() | Log an error |
| log_get_verbosity() | Get the current log level |
| log_highlight() | Highlight a message and write it to standard output |
| log_increase_verbosity() | Increase the log level |
| log_info() | Log an informational message |
| log_set_verbosity() | Change the current log level |
| log_stacktrace() | Write the call hierarchy to standard output |
| log_warn() | Log a warning |
Log a debug message
log_debug "${messages[@]}"
log_debug <<< "$messages"
The log_debug() function writes debug messages to standard error and the script's log file. If debug messages
were passed as arguments, this function will treat each argument as a debug message. Otherwise, this function
will read debug messages line-by-line from standard input.
Each line of output is prefixed with a timestamp, log tag, as well as the name of the source file and the line
number that the function was called from.
Messages will only be logged if the current log level is __log_debug or above.
| Return value | Meaning |
|---|---|
| 0 | The message was written successfully |
| 1 | The message could not be logged |
If this function is invoked without arguments, messages will be read from standard input.
This function does not write to standard output.
This function will write one message per line to standard error.
Decrease the log level
log_decrease_verbosity
The log_decrease_verbosity() function lowers the log level of the executing script by one step. If the log level
is at __log_error, it will remain unchanged.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
This function does not read from standard input.
This function does not write to standard output.
This function does not write to standard error.
Log an error
log_error "${messages[@]}"
log_error <<< "$messages"
The log_error() function writes error messages to standard error and the script's log file. If error messages
were passed as arguments, this function will treat each argument as an error message. Otherwise, this function
will read error messages line-by-line from standard input. Each line of output is prefixed with a timestamp and
log tag.
Error messages are always logged, regardless of the log level.
| Return value | Meaning |
|---|---|
| 0 | The message was written successfully |
| 1 | The message could not be logged |
If this function is invoked without arguments, messages will be read from standard input.
This function does not write to standard output.
This function will write one message per line to standard error.
Get the current log level
log_get_verbosity
The log_get_verbosity() function writes the current log level to standard output.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
This function does not read from standard input.
An integer value indicating the current log level is written to standard output.
This function does not write to standard error.
Highlight a message and write it to standard output
log_highlight "$tag" "${lines[@]}"
log_highlight "$tag" <<< "$lines"
The log_highlight() function adds markers with a tag $tag around the lines passed in $lines and writes them
to standard output, making the lines easier to find in a large amount of log output.
If no lines were passed as arguments, this function reads the data to be highlighted from standard input.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
If this function is invoked without arguments, data to be highlighted will be read from standard input.
Highlighted data will be written to standard output.
This function may write a message to standard error if standard input is not readable.
Increase the log level
log_increase_verbosity
The log_increase_verbosity() function raises the log level of the executing script by one step. If the log level
is at __log_debug, it will remain unchanged.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
This function does not read from standard input.
This function does not write to standard output.
This function does not write to standard error.
Log an informational message
log_info "${messages[@]}"
log_info <<< "$messages"
The log_info() function writes informational messages to standard error and the script's log file. If messages
were passed as arguments, this function will treat each argument as a message. Otherwise, this function will read
messages line-by-line from standard input. Each line of output is prefixed with a timestamp and log tag.
Messages will only be logged if the log level is __log_info or above.
| Return value | Meaning |
|---|---|
| 0 | The message was written successfully |
| 1 | The message could not be logged |
If this function is invoked without arguments, messages will be read from standard input.
This function does not write to standard output.
This function will write one message per line to standard error.
Change the current log level
log_set_verbosity "$verbosity"
The log_set_verbosity() function sets the log level of the executing script to $verbosity. If the value passed in
$verbosity is not a valid log level, the function will set it to the nearest valid log level.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
This function does not read from standard input.
This function does not write to standard output
This function does not write to standard error.
Write the call hierarchy to standard output
log_stacktrace
The log_stacktrace() function writes the call hierarchy of the calling function to standard output, allowing
the user to determine where a particular function was called from. The output written to standard output includes
file names, function names, and the line numbers that functions were called from. Indentation is used to visually
highlight the nesting of function calls.
| Return value | Meaning |
|---|---|
| 0 | Success (always returned) |
This function does not read from standard input.
The stacktrace of the calling function is written to standard output.
This function does not write to standard error.
Log a warning
log_warn "${messages[@]}"
log_warn <<< "$messages"
The log_warn() function writes warning messages to standard error and the script's log file. If messages were
passed as arguments, this function will treat each argument as a message. Otherwise, this function will read
messages line-by-line from standard input. Each line of output is prefixed with a timestamp and log tag.
Messages will only be logged if the log level is __log_warning or above.
| Return value | Meaning |
|---|---|
| 0 | The message was written successfully |
| 1 | The message could not be logged |
If this function is invoked without arguments, messages will be read from standard input.
This function does not write to standard output.
This function will write one message per line to standard error.