Shellib Log Library

A simple and versatile Bash logging utility that supports different log levels, optional timestamps, and optional file output.

Installation and Usage

The recommended approach is to use the grab script:

source $(grab github.com/shellib/log)

This will fetch and source library.sh directly from GitHub. Once sourced, the log function becomes available in your shell.

Example

# Source the log library.
source $(grab github.com/shellib/log)

# Log messages of various levels.
log DEBUG "Debug message."        # Will show if LOG_THRESHOLD <= DEBUG
log INFO "Information message."   # Will show if LOG_THRESHOLD <= INFO
log WARN "Warning message."       # Will show if LOG_THRESHOLD <= WARN
log ERROR "Error message."        # Always logged if threshold is ERROR or below

Features

1. Threshold-based Logging
   Controlled via the LOG_THRESHOLD environment variable. Possible values are DEBUG, INFO, WARN, ERROR. Defaults to INFO if unset.

2. Optional Log File
   If the LOG_FILE environment variable is set, all log messages are appended to the specified file. Otherwise, logs are printed to stdout or stderr (for errors).

3. Timestamps
   To include timestamps in your logs, pass -t or --with-timestamps as the first argument to the log function. For example:

   log -t INFO "Starting the program..."

   Timestamps are in the format: YYYY-MM-DD HH:MM:SS.

4. DRY_RUN Mode
   If DRY_RUN is set to true, each log line will be prefixed with [DRY_RUN]. This can be useful for simulating actions without performing them.

Environment Variables

• LOG_THRESHOLD
  Sets the minimum level to log. Valid values: DEBUG, INFO, WARN, ERROR. Defaults to INFO.

• LOG_FILE
  If specified, log messages go to this file (appended). Otherwise, logs go to terminal output.

• DRY_RUN
  If true, [DRY_RUN] is added to each log line.

Command Reference

log [FLAGS] LEVEL MESSAGE

Where:

• FLAGS can be -t or --with-timestamps.
• LEVEL is one of DEBUG, INFO, WARN, ERROR.
• MESSAGE is the text to log.

Example:

# with timestamps
log --with-timestamps INFO "Some info message."

# regular usage
log ERROR "Badness happened!"