Sign inSign up

unfor19/bash-logging

By unfor19

•Updated about 5 years ago

Image
0

1.3K

unfor19/bash-logging repository overview

⁠bash-logging

Publish Latest Dockerhub pulls

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

Tag summary

Content type

Image

Digest

Size

3.5 MB

Last updated

about 5 years ago

docker pull unfor19/bash-logging