Shell logging

Shell library for logging.

Table of Contents

• Shell logging
  • Table of Contents
  • Outline
  • How to use?
    • Prerequisites
    • Installation
  • Features
    • Config file
    • Supported parameters
      • Log level
      • Output format
      • Date format
      • Header
      • Text color
      • Text format

Outline

• Supports 5 log levels: debug, info, warning, error, off.
• Supports 3 output formats: json, xml and text.
• Supports output customization for text output format.
• Supports colorized/non-colorized printing.
• Supports customization via environment variables.
• Supports customization via configuration file.

How to use?

Prerequisites

The following tools have to be available on a machine prior using this library:

• bash >=4.0
• jq - Only if you're using config file or JSON output format.

Installation

bpkg install fabasoad/sh-logging

See installation options for more details.

Features

Config file

For each log function call you can specify a path to config file. Example:

fabasoad_log "info" "This is info message" "./config.json"

Where ./config.json has the following content:

{
  "version": "v0.1.0",
  "config": {
    "date-format": "%Y-%m-%d %T",
    "header": "fabasoad-log-json",
    "log-level": "info",
    "output-format": "text",
    "text-color": false,
    "text-format": "[<header>] <timestamp> level=<level> <message>"
  }
}

In your application you can wrap this function with your own function, so you do not need to specify all the parameters every time. Example:

log_info() {
  fabasoad_log "info" "${1}" "./config.json"
}

log_info "This is info message"

Supported parameters

Log level

Level of logging to produce.

• Environment variable: FABASOAD_LOG_CONFIG_LOG_LEVEL.
• Possible options: debug, info, warning, error, off.
• Default value: info.

The rules are the following:

• If log level is off then no logs will be produced.
• If log level is debug then all logs will be produced.
• If log level is info then all logs except of debug logs will be produced.
• If log level is warning then only warning and error logs will be produced.
• If log level is error then only error logs will be produced.

Output format

The format of logs to produce.

• Environment variable: FABASOAD_LOG_CONFIG_OUTPUT_FORMAT.
• Possible options: text, json, xml.
• Default value: text.

Date format

Format that passes to date shell command, e.g. if you want date +%s to be used then you need to use %s.

• Environment variable: FABASOAD_LOG_CONFIG_DATE_FORMAT.
• Possible options: Any string value.
• Default value: %Y-%m-%d %T.

Header

It is usually used to mention your program name in the logs. For example, if you want your logs to be something like this:

[my-app] [error] Validation error!

Then you need to use my-app as a header value.

• Environment variable: FABASOAD_LOG_CONFIG_HEADER.
• Possible options: Any string value.
• Default value: fabasoad-log.

Text color

Enables/disables coloring of the logs output.

• Environment variable: FABASOAD_LOG_CONFIG_TEXT_COLOR.
• Possible options: true, false.
• Default value: true.

Text format

The format/pattern of the text logs. It works only if output format is set to text.

• Environment variable: FABASOAD_LOG_CONFIG_TEXT_FORMAT.
• Possible options: Any string value.
• Default value: [<header>] <timestamp> level=<level> <message>.

It supports the following templates: <header>, <timestamp>, <level>, <message>. For example, if you want your logs to be like this:

[my-app] [info] "2024-07-14 21:30:47" Downloading binary

Then you need to set text format to [<header>] [<level>] "<timestamp>" <message>.

Contributions