Skip to content

Lightweight POSIX shell compatible library for logging

License

Notifications You must be signed in to change notification settings

fabasoad/sh-logging

Repository files navigation

Shell logging

Stand With Ukraine GitHub release security linting

Shell library for logging.

Table of Contents

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

More information on installation options you can find here.

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>.