shlog

Easy Logging in the shell

         __    __           
   _____/ /_  / /___  ____ _
  / ___/ __ \/ / __ \/ __ `/
 (__  ) / / / / /_/ / /_/ / 
/____/_/ /_/_/\____/\__, /  
                   /____/   
logging bash

• USAGE
• INSTALL
  • Requirements
  • From source - system-wide
  • From source - home directory
  • From source - project specific
  • bpkg bash package manager
• CONFIGURATION
  • Log levels
  • Configuration files
  • Colors
    • SHLOG_STYLE_TRACE
    • SHLOG_STYLE_DEBUG
    • SHLOG_STYLE_INFO
    • SHLOG_STYLE_WARN
    • SHLOG_STYLE_ERROR
    • SHLOG_STYLE_MODULE
    • SHLOG_STYLE_LINE
    • SHLOG_STYLE_DATE
    • SHLOG_STYLE_RESET
  • Outputs
    • SHLOG_TERM
    • SHLOG_FILE
  • Enabling / Disabling colors
    • SHLOG_TERM_COLORIZE
    • SHLOG_FILE_COLORIZE
  • Term Output options
    • SHLOG_TERM_OUTPUT
  • File Output options
    • SHLOG_FILE_FILENAME
  • Formatting Log output
    • SHLOG_DATE_FORMAT
    • SHLOG_PROFILE_PRECISION
    • SHLOG_FORMAT
      • %level
      • %date
      • %module
      • %line
      • %msg
  • Debugging shlog
    • SHLOG_SELFDEBUG
• FAQ
  • How to turn off logging?
  • How to debug the logging?
  • How to log to STDOUT instead of STDERR?
  • How to log to a file?
  • How to enable or disable color output?
  • Logging is slow and module is always shlog?
  • shlog doesn't respect my configuration?
  • How to reload the configuration?
  • How can I execute code just before the log message is printed?
• API
  • shlog
  • shlog::reload
  • shlog::selfdebug
  • shlog::dump
  • shlog::pipe
  • shlog::profile
• COPYRIGHT

USAGE

Usage: shlog [-v] [-l LEVEL] [-m MODULE] [-d VARNAME] [-x EXIT_STATUS] <msg>

    Options:

        -h --help               Show this help
        -l --level LEVEL        Log at this LEVEL [Default: trace]
        -m --module MODULE      Log as this MODULE [Default: calling script]
        -d --dump VARNAME       Dump variable VARNAME
        -x --exit EXIT_STATUS   Log and exit with EXIT_STATUS

INSTALL

Requirements

• bash >= 4 (This is a guess but seems likely)

From source - system-wide

git clone https://github.com/kba/shlog
cd shlog
make install

From source - home directory

To install to your home directory, use the PREFIX make variable:

make install PREFIX=$HOME/.local

Make sure you have PATH="$HOME/.local/bin:$PATH in your shell startup script.

From source - project specific

shlog comes pre-built, so you can use it in your project, e.g. by including the shlog repo as a git submodule:

cd ~/myproject
git submodule add https://github.com/kba/shlog deps/shlog

In your script, add ~myproject/deps/shlog/dist to your path and source "$(which shlog)".

bpkg bash package manager

bpkg install 'kba/shlog'

CONFIGURATION

Log levels

shlog knows five levels, from lowest to highest priority:

• trace
• debug
• info
• warn
• error

Configuration files

shlog will look in three places for a configuration file with environment variables:

• /etc/default/shlogrc
• $HOME/.config/shlog/shlogrc
• $PWD/.shlogrc

Environment variables in any of those files will be sourced in that order to configure the logging.

Colors

Defines the colors to use for various part of the log message if SHLOG_USE_STYLES is set for that output.

SHLOG_STYLE_TRACE

SHLOG_STYLE_TRACE : %level==trace : Default: magenta

SHLOG_STYLE_DEBUG

SHLOG_STYLE_DEBUG : %level==debug : Default: cyan

SHLOG_STYLE_INFO

SHLOG_STYLE_INFO : %level==info : Default: cyan

SHLOG_STYLE_WARN

SHLOG_STYLE_WARN : %level==warn : Default: yellow

SHLOG_STYLE_ERROR

SHLOG_STYLE_ERROR : %level==error : Default: bold red

SHLOG_STYLE_MODULE

SHLOG_STYLE_MODULE : %module : Default: bold

SHLOG_STYLE_LINE

SHLOG_STYLE_LINE : %line : Default: bold green

SHLOG_STYLE_DATE

SHLOG_STYLE_DATE : %date : Default: none

SHLOG_STYLE_RESET

SHLOG_STYLE_RESET : (after every style) : Default: �[0m

Outputs

Defines the minimum level at which to log to different outputs

SHLOG_TERM

SHLOG_TERM: Minimum level for terminal. Default: trace

SHLOG_FILE

SHLOG_FILE: Minimum level for file logging. Default: off

Enabling / Disabling colors

Defines which outputs should use styles.

SHLOG_TERM_COLORIZE

SHLOG_TERM_COLORIZE: Use styles on terminal . Default: "true"

SHLOG_FILE_COLORIZE

SHLOG_FILE_COLORIZE: Use styles on file . Default: "false"

Term Output options

SHLOG_TERM_OUTPUT

Whether to output to stderr (the default) or stdout.

File Output options

SHLOG_FILE_FILENAME

SHLOG_FILE_FILENAME: Filename of the file to log to.

Default: basename of $0 with out extension + .log in /tmp

Formatting Log output

SHLOG_DATE_FORMAT

SHLOG_DATE_FORMAT: strftime(3) pattern for the %date part of a log message, to be passed to printf.

Default: %(%F %T)T (i.e. YYYY-MM-DD HH:MM:SS)

SHLOG_PROFILE_PRECISION

SHLOG_PROFILE_PRECISION: The granularity with which shlog::profile will print the elapsed time. Can be ns for nano-second precision or ms for millisecond precision (the default).

SHLOG_FORMAT

SHLOG_FORMAT: printf-Pattern for the log message.

Default: [%level] %date %module:%line - %msg

Custom patterns:

%level

%level: The log level

%date

%date: The timestamp of the log message, see SHLOG_DATE_FORMAT

%module

%module: The calling module

%line

%line: Line number of the calling script

%msg

%msg: The actual log message

Debugging shlog

SHLOG_SELFDEBUG

SHLOG_SELFDEBUG: If set to "true", shlog will output its configuration upon first initialization.

Default: false

FAQ

How to turn off logging?

Set the SHLOG_SILENT variable to a non-zero value to discard all log messages within that shell:

SHLOG_SILENT=true some-noisy-script.sh

How to debug the logging?

To debug the logging process itself, set the SHLOG_SELFDEBUG variable to a non zero value:

SHLOG_SELFDEBUG=true some-command.sh

This will make shlog output its configuration upon initialization and also log all the files it sourced.

How to log to STDOUT instead of STDERR?

Set SHLOG_TERM_OUTPUT to stdout:

SHLOG_TERM_OUTPUT=stdout
SHLOG_TERM=debug # or trace, info, warn, error

How to log to a file?

Enable the file output in your configuration file:

SHLOG_FILE=trace
SHLOG_FILE_FILENAME=$PWD/myscrip.log

SHLOG_FILE_FILENAME is optional, will default to a file in /tmp derived from $0 if not set explicitly

How to enable or disable color output?

Define SHLOG_<output>_COLORIZE. The default is:

SHLOG_TERM_COLORIZE=true
SHLOG_FILE_COLORIZE=false

Logging is slow and module is always shlog?

While you can use shlog as a command line script, it's much faster to use it as a shell function.

Make sure you source the shlog script, otherwise every log command is spawning a new shell. Compare:

Slow:

time for i in $(seq 1000); do shlog -l info test; done
# ...
# real  0m4.466s
# user  0m0.164s
# sys   0m0.172s

Fast:

source "$(which shlog)"
time for i in $(seq 1000); do shlog -l info test; done
# ...
# real  0m0.889s
# user  0m0.408s
# sys   0m0.136s

shlog doesn't respect my configuration?

How to reload the configuration?

Call shlog::reload, without any arguments. It will reconfigure all variables and all changes should be visible then.

How can I execute code just before the log message is printed?

You can create a function shlog::before that will be called whenever shlog is called. Some use cases:

• Move the cursor to an appropriate position for full-screen terminal apps
• Rotate a log file
• Add one-off solutions for special cases (e.g. send an email for specific condition)

API

shlog

source

The logging function

shlog::reload

source

(Re-)initialize the logging by reading configuration files and setting up variables.

shlog::selfdebug

source

Dump the configuration to STDOUT.

See shlog::dump.

shlog::dump

source

Dump a variable by calling declare -p

shlog::pipe

Read lines from STDIN and log them.

See shlog for options.

shlog::profile

Profile the execution time of shell code.

• Register a name with the profiler: shlog::profile "my-feature"
• Whenever you call shlog::profile -log "my-feature" [shlog-args...] from now on, a log message with the elapsed time will be output. [shlog-args...] are passed on to shlog

Example:

shlog::profile 'sleep'
sleep 1.7
shlog::profile -log 'sleep' -l "info"
sleep 0.7
shlog::profile -log 'sleep' -l "debug"

# [info ] - Profiled 'sleep': 1705 ms
# [debug] - Profiled 'sleep': 708 ms

COPYRIGHT

The MIT License (MIT)

Copyright (c) 2016 Konstantin Baierer

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.