L_log¶
Log library that provides functions for logging messages.
Usage¶
The L_log module is initialized with level INFO on startup.
To log a message you can use several functions functions. Each of these function takes a message to print.
L_trace "Tracing message"
L_debug "Debugging message"
L_info "Informational message"
L_notice "Notice message"
L_warning "Warning message"
L_error "Error message"
L_critical "Critical message"
By default, if one argument is given to the function, it is outputted as-is.
If more arguments are given, they are parsed as a printf formatting string.
L_info "hello %s" # logs 'hello %s'
L_info "hello %s" "world" # logs 'hello world'
The configuration of log module is done with L_log_configure.
declare info verbose
L_argparse -- -v --verbose action=store_1 ---- "$@"
if ((verbose)); then level=debug; else level=info; fi
L_log_configure -l "$level"
The logging functions accept the -s option to to increase logging stack information level.
your_logger() {
L_info -s 1 -- "$@"
}
somefunc() {
L_info hello
your_logger world
}
All these functions forward messages to L_log which is main entrypoint for logging.
L_log takes two options, -s for stacklevel and -l for loglevel.
The loglevel can be specified as a sting info or INFO or L_LOGLEVEL_INFO or as a number 30 or $L_LOGLEVEL_INFO.
L_log -s 1 -l debug -- "This is a debug message"
Configuration¶
The logging can be configured with L_log_configure.
It supports custom log line filtering, custom formatting and outputting, independent.
my_log_formatter() {
printf -v L_logline "%(%c)T: %s %s" -1 "${L_LOGLEVEL_NAMES[L_logline_loglevel]}" "$*"
}
my_log_ouputter() {
echo "$L_logline" | logger -t mylogmessage
echo "$L_logline" >&2
}
my_log_filter() {
# output only logs from functions starting with L_
[[ $L_logline_funcname == L_* ]]
}
L_log_configure -l debug -F my_log_formatter -o my_log_ouputter -s my_log_selector
There are these formatting functions available:
L_log_format_default- defualt log formatting function.L_log_format_long- long formatting with timestamp, source, function, line, level and message.L_log_format_json- format log as JSON lines.
Available variables in filter, outputter and formatter functions:¶
There are several variables L_logline_* available for callback functions:
$L_logline- The variable should be set by the formatting function and printed by the outputting function.$L_logline_level- Numeric logging level for the message.$L_logline_levelname- Text logging level for the message. Empty if unknown.$L_logline_funcname- Name of function containing the logging call.$L_logline_source- The BASH_SOURCE where the logging call was made.$L_logline_lineno- The line number in the source file where the logging call was made.$L_logline_stacklevel- The offset in stack to where the logging call was made.${L_LOGLEVEL_COLORS[L_logline_levelno]:-}- The color for the log line.$L_logline_color- Set to 1 if line should print color. Set to empty otherwise.- This is used in templating.
${L_logline_color:+${L_LOGLEVEL_COLORS[L_logline_levelno]:-}colored${L_logline_color:+$L_COLORRESET}
- This is used in templating.
Generated documentation from source:¶
logging library
This library is meant to be similar to python logging library.
was log system configured?
_L_logconf_configured=0
int current global log level
_L_logconf_level=$L_LOGLEVEL_INFO
1 or 0 or ''. Should we use the color for logging output?
_L_logconf_color=
if this regex is set, allow elements
_L_logconf_selecteval=
default formatting function
_L_logconf_formateval='L_log_format_default "$@"'
default outputting function
_L_logconf_outputeval=L_log_output_to_stderr
Example
L_log_set_level ERROR
L_error "this is an error"
L_info "this is information"
L_debug "This is debug"
convert log level to log name
get color associated with particular loglevel
Shellcheck disable= SC2153
Configure L_log module.
Example
L_log_configure \
-l debug \
-c 0 \
-f 'printf -v L_logline "${@:2}"' \
-o 'printf "%s\n" "$L_logline" >&2' \
-s '[[ $L_logline_source == */script.sh ]]'
Options:
-
-hPrint this help and return 0. -
-rAllow for reconfiguring L_log system. Otherwise the next call of this function is ignored. -
-l <LOGLEVEL>Set loglevel. Can be \$L_LOGLEVEL_INFO INFO or 30. Default: $_L_logconf_level -
-c <BOOL>Set to 1 to enable the use of color, set to 0 to disable the use of color.
Set to '' empty string to detect if stdout has color support. Default: ''
-
-f <FORMATEVAL>Evaluate expression for formatting. Default: 'L_log_format_default "$@"'
The function should format arguments and put the message into the L_logline variable.
-
-F <FORMATFUNC>Equal to -f '"$@"'. Shorthand to use a function. -
-s <SELECTEVAL>If eval "SELECTEVAL" exits with nonzero, do not print the line. Default: '' -
-o <OUTPUTEVAL>Evaluate expression for outputting. Default: L_log_output_to_stderr
The function should output the content of L_logline.
-
-LEqual to -F L_log_format_long -
-JEqual to -F L_log_format_json
Arguments: Takes no arguments
increase log level
Argument:
$1
decrease log level
Argument:
$1
Convert log string to number
Arguments:
-
$1str variable name -
$2int|str loglevel likeINFOinfoor30
Check if log of such level is enabled to log.
Argument:
$1
str|int loglevel or log string
Default logging formatting
Arguments:
-
$1str log line printf format string -
$@any log line printf arguments
Format logline with timestamp information.
Arguments:
-
$1str log line printf format string -
$@any log line printf arguments
Output logs in json format.
Shellcheck disable= SC2059
Output L_logline to stderr.
Output L_logline with logger.
Argument:
$@
message to output
main logging entrypoint
Options:
-
-s <int>Increment stacklevel by this much -
-l <int|string>loglevel to print log line as
Argument:
$@
any log arguments
Shellcheck disable= SC2140
Return: 0 if nothing was logged, or the exit status of formatter && outputter functions.
output a critical message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a error message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a warning message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a notice
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a information message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a debugging message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
output a tracing message
Option:
-s <int>
stacklevel increase
Argument:
$1
message
Output a critical message and exit the script with 2.
Argument:
$@
L_critical arguments
log a command and then execute it
Is not affected by L_dryrun variable.
Argument:
$@
command to execute
Output a green information message
Options:
-
-s <int> -
-l <level>
Argument:
$1
message
set to 1 if L_run should not execute the function.
Logs the quoted argument with a leading +.
if L_dryrun is nonzero, executes the arguments.
Options:
-
-l <loglevel>Set loglevel. -
-s <stacklevel>Increment stacklevel by this number. -
-hPrint this help and return 0.
Argument:
$@
command to execute
Uses environment variable:
L_dryrun