bash-logging

A Logging Framework for Bash. This project aims to provide a solution that can be implemented with a single file import source logging.sh.

To keep your script as a single file, you can copy paste the contents of logging.sh to the top your script.

Usage

1. Download the logging.sh script

   TARGET_URL="https://raw.githubusercontent.com/unfor19/bash-logging/master/logging.sh" && \
   wget -O logging.sh "$TARGET_URL" && \
   chmod +x ./logging.sh

2. Import the logging.sh file in your script

   source logging.sh

3. Set the _LOGGING_LEVELS according to your needs, currently there are four (4) levels, see logging.sh

   1. DBG=0 - Logs verbose usage messages, useful for debugging the script
   2. INF=1 - Logs application messages
   3. WRN=2 - Logs warning messages
   4. OFF=3 - No logs at all

4. Use the functions log_msg and err_msg in your code, the entrypoint.sh file contains a full example of an application that logs the current disk usage.

   • log_msg $MSG $LOGGING_LEVEL=INF
   • err_msg $MSG $EXIT_CODE=1

Examples

Docker

Run as a Docker container

docker run --rm -it unfor19/bash-logging:example "/" 85 92

# Output
[INF] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Getting disk usage ...
[INF] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Disk usage for the path "/" is 92%
[WRN] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Disk usage is higher than the warning threshold of 85%

From Source

I've create a sample application that makes it easier to understand the logging mechanism.

1. Download entrypoint.sh and logging.sh

   LOGGING_URL="https://raw.githubusercontent.com/unfor19/bash-logging/master/logging.sh" && \
   ENTRYPOINT_URL="https://raw.githubusercontent.com/unfor19/bash-logging/master/entrypoint.sh" && \
   wget "$LOGGING_URL" "$ENTRYPOINT_URL" && \
   chmod +x ./entrypoint.sh ./logging.sh

2. Provide arguments or variables

   ./entrypoint.sh "$DISK_USAGE_PATH" "$WARNING_THRESHOLD" "$MOCKED_DISK_USAGE"

3. Using default values DISK_USAGE_PATH="/", WARNING_THRESHOLD=85, MOCKED_DISK_USAGE=""

   ./entrypoint.sh

   # Output
   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Getting disk usage ...
   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Disk usage for the path "/" is 6%
   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Disk usage is lower than the warning threshold of 85%

Tests Output

Here are the results of tests.sh

Expand/Collpase

-------------------------------------------------------
[LOG] Default Values - Should pass
[LOG] Executing: bash ./entrypoint.sh
[LOG] Output:

[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path "/" is 54%
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Single Argument - Should pass
[LOG] Executing: bash ./entrypoint.sh /
[LOG] Output:

[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path "/" is 54%
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Two Arguments - Should pass
[LOG] Executing: bash ./entrypoint.sh / 80
[LOG] Output:

[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path "/" is 54%
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 80%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] All Arguments - Should pass
[LOG] Executing: bash ./entrypoint.sh / 75 92
[LOG] Output:

[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path "/" is 92%
[WRN] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is higher than the warning threshold of 75%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Empty Values - Should pass
[LOG] Executing: bash entrypoint.sh   
[LOG] Output:

[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path "/" is 54%
[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Logging level - OFF - Should pass
[LOG] Executing: bash entrypoint.sh
[LOG] Output:



[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Logging level - Debugging - Should pass
[LOG] Executing: bash entrypoint.sh / 75 92
[LOG] Output:

[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Getting disk usage ...
[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Finished getting disk usage 92 with the given path /
[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Warning threshold is 75
[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage for the path "/" is 92%
[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%
[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Successfully completed disk usage process

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Logging level - Warning - Should pass
[LOG] Executing: bash entrypoint.sh / 75 92
[LOG] Output:

[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%

[LOG] Test passed as expected
-------------------------------------------------------
[LOG] Logging level - Unknown - Should fail
[LOG] Executing: bash entrypoint.sh / 75 92
[LOG] Output:

[ERR] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: [EXIT_CODE=3] The variable LOGGING_LEVEL "WILLY" does not exist in INF OFF WRN DBG

[LOG] Test failed as expected
-------------------------------------------------------
[LOG] Unknown inline logging level - Should fail
[LOG] Executing: bash entrypoint.sh / 75 92
[LOG] Output:

[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Getting disk usage ...
[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage for the path "/" is 92%
[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%
[ERR] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: [EXIT_CODE=2] The argument "WONKA" does not exist in INF OFF WRN DBG

[LOG] Test failed as expected

Advanced Bash Expressions

In the following section you'll find documenation about the advanced Bash expressions that I used in this project.

Piping the data

Using | to pipe the data and getting the fifth element of the final line (Milla Jovovich? Bruce Willis?)

get last line | squash spaces     | split string by " " and get the Fifth Element 
tail -1       | tr -s "[:space:]" | cut -d" " -f5

This expression is used in the code in

path="/" # pseudo code
usage_msg="$(df -h "$path")"
echo -e "$usage_msg" # print temporary variable, including line breaks `-e`
percentage_msg="$(echo "$usage_msg" | tail -1 | tr -s "[:space:]" | cut -d" " -f5)"
echo "$percentage_msg" # print results

# Output - varies per machine
6%

Associative Array Keys As Array

To get Keys of a given associative array, use the ! character.

declare -A ASSOCIATIVE_ARRAY=([FIRST]=1 [SECOND]=2) && \
echo ${!ASSOCIATIVE_ARRAY[*]} && \
declare -a KEYS_ARRAY=("${!ASSOCIATIVE_ARRAY[*]}") && \
echo "Keys Array: ${KEYS_ARRAY[@]}"

# Output
FIRST SECOND
Keys Array: FIRST SECOND

This expression is used in the code in - ${!_LOGGING_LEVELS[*]}

Initializing Variables

1. Use the first argument $1 as the default value; if empty, use the var $DISK_USAGE_PATH

   _DISK_USAGE_PATH="${1:-"$DISK_USAGE_PATH"}"

2. Check if default value is set, if not, set to /

   _DISK_USAGE_PATH="${_DISK_USAGE_PATH:-"/"}"

Substring

Replace all % instances with "" - The chars // after MY_VAR stands for "all instances"; when using a single / it removes the first instance only

${MY_VAR//replace_this/with_this}

This expression is used in the code in

percentage_msg="$(echo "$usage_msg" | tail -1 | tr -s "[:space:]" | cut -d" " -f5)" # pseudo code
percentage="${percentage_msg//%/}"
echo "$percentage"

# Output - varies per machine
6

Datetime

$(date +%s) # DDD MMM DD HH:MM:SS TZ YYYY
$(date)     # 1234567890 unix timestamp

Contributing

Report issues/questions/feature requests on the Issues section.

Pull requests are welcome! These are the steps:

1. Fork this repo
2. Create your feature branch from master (git checkout -b my-new-feature)
3. Add the code of your new feature
4. Run tests on your code, feel free to add more tests

   $ bash tests.sh
   ... # All good? Move on to the next step

5. Commit your remarkable changes (git commit -am 'Added new feature')
6. Push to the branch (git push --set-up-stream origin my-new-feature)
7. Create a new Pull Request and provide details about your changes

References

1. Simple logging levels in Bash
2. Create timestamp variable in bash script

Authors

Created and maintained by Meir Gabay

License

This project is licensed under the MIT License - see the LICENSE file for details