{"id":16725282,"url":"https://github.com/unfor19/bash-logging","last_synced_at":"2026-05-20T07:30:58.839Z","repository":{"id":122056810,"uuid":"384564513","full_name":"unfor19/bash-logging","owner":"unfor19","description":"A Logging Framework for Bash. This project aims to provide a solution that can be implemented with a single file import `source logging.sh`.","archived":false,"fork":false,"pushed_at":"2021-07-10T18:51:18.000Z","size":95,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-01-22T05:17:46.472Z","etag":null,"topics":["bash","best-practices","convention","logging","script"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/unfor19.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-07-09T22:34:58.000Z","updated_at":"2024-02-24T18:10:53.000Z","dependencies_parsed_at":null,"dependency_job_id":"54ee5c45-fb4c-422b-beda-7bafb7295777","html_url":"https://github.com/unfor19/bash-logging","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unfor19%2Fbash-logging","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unfor19%2Fbash-logging/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unfor19%2Fbash-logging/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/unfor19%2Fbash-logging/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/unfor19","download_url":"https://codeload.github.com/unfor19/bash-logging/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243746234,"owners_count":20341203,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bash","best-practices","convention","logging","script"],"created_at":"2024-10-12T22:48:38.233Z","updated_at":"2026-05-20T07:30:58.811Z","avatar_url":"https://github.com/unfor19.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bash-logging\n\n[![Publish Latest](https://github.com/unfor19/bash-logging/actions/workflows/publish-latest.yml/badge.svg)](https://github.com/unfor19/bash-logging/actions/workflows/publish-latest.yml) [![Dockerhub pulls](https://img.shields.io/docker/pulls/unfor19/bash-logging)](https://hub.docker.com/r/unfor19/bash-logging)\n\nA Logging Framework for Bash. This project aims to provide a solution that can be implemented with a single file import `source logging.sh`.\n\nTo keep your script as a single file, you can copy paste the contents of [logging.sh](https://github.com/unfor19/bash-logging/blob/master/logging.sh) to the top your script.\n\n## Usage\n\n1. Download the [logging.sh](https://github.com/unfor19/bash-logging/blob/master/logging.sh) script\n    ```bash\n    TARGET_URL=\"https://raw.githubusercontent.com/unfor19/bash-logging/master/logging.sh\" \u0026\u0026 \\\n    wget -O logging.sh \"$TARGET_URL\" \u0026\u0026 \\\n    chmod +x ./logging.sh\n    ```\n1. Import the [logging.sh](https://github.com/unfor19/bash-logging/blob/master/logging.sh) file in your script\n   ```bash\n   source logging.sh\n   ```\n\n1. Set the `_LOGGING_LEVELS` according to your needs, currently there are four (4) levels, see [logging.sh](https://github.com/unfor19/bash-logging/blob/master/logging.sh#L5)\n   1. `DBG=0` - Logs verbose usage messages, useful for debugging the script\n   2. `INF=1` - Logs application messages\n   3. `WRN=2` - Logs warning messages\n   4. `OFF=3` - No logs at all\n\n1. Use the functions `log_msg` and `err_msg` in your code, the [entrypoint.sh](https://github.com/unfor19/bash-logging/blob/master/entrypoint.sh) file contains a full example of an application that logs the current disk usage.\n   - `log_msg $MSG $LOGGING_LEVEL=INF`\n   - `err_msg $MSG $EXIT_CODE=1`\n\n\n## Examples\n\n### Docker\n\nRun as a [Docker](https://www.docker.com/why-docker) container\n\n```bash\ndocker run --rm -it unfor19/bash-logging:example \"/\" 85 92\n```\n\n```bash\n# Output\n[INF] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Getting disk usage ...\n[INF] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Disk usage for the path \"/\" is 92%\n[WRN] 1625942574 Sat Jul 10 18:42:54 UTC 2021 :: Disk usage is higher than the warning threshold of 85%\n```\n\n### From Source\n\nI've create a sample application that makes it easier to understand the logging mechanism.\n\n1. Download [entrypoint.sh](https://github.com/unfor19/bash-logging/blob/master/entrypoint.sh) and [logging.sh](https://github.com/unfor19/bash-logging/blob/master/logging.sh)\n    ```bash\n    LOGGING_URL=\"https://raw.githubusercontent.com/unfor19/bash-logging/master/logging.sh\" \u0026\u0026 \\\n    ENTRYPOINT_URL=\"https://raw.githubusercontent.com/unfor19/bash-logging/master/entrypoint.sh\" \u0026\u0026 \\\n    wget \"$LOGGING_URL\" \"$ENTRYPOINT_URL\" \u0026\u0026 \\\n    chmod +x ./entrypoint.sh ./logging.sh\n    ```\n2. Provide arguments or variables\n    ```bash\n    ./entrypoint.sh \"$DISK_USAGE_PATH\" \"$WARNING_THRESHOLD\" \"$MOCKED_DISK_USAGE\"\n    ```\n\n3. Using default values `DISK_USAGE_PATH=\"/\"`, `WARNING_THRESHOLD=85`, `MOCKED_DISK_USAGE=\"\"`\n   ```bash\n   ./entrypoint.sh\n   ```\n\n   ```bash\n   # Output\n   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Getting disk usage ...\n   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Disk usage for the path \"/\" is 6%\n   [INF] 1625928547 Sat Jul 10 17:49:07 IDT 2021 :: Disk usage is lower than the warning threshold of 85%\n   ```\n\n### Tests Output\n\nHere are the results of [tests.sh](https://github.com/unfor19/bash-logging/blob/master/tests.sh)\n\n\u003cdetails\u003e\u003csummary\u003eExpand/Collpase\u003c/summary\u003e\n\n\u003c!-- replacer_start_tests --\u003e\n```\n-------------------------------------------------------\n[LOG] Default Values - Should pass\n[LOG] Executing: bash ./entrypoint.sh\n[LOG] Output:\n\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path \"/\" is 54%\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Single Argument - Should pass\n[LOG] Executing: bash ./entrypoint.sh /\n[LOG] Output:\n\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path \"/\" is 54%\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Two Arguments - Should pass\n[LOG] Executing: bash ./entrypoint.sh / 80\n[LOG] Output:\n\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path \"/\" is 54%\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 80%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] All Arguments - Should pass\n[LOG] Executing: bash ./entrypoint.sh / 75 92\n[LOG] Output:\n\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path \"/\" is 92%\n[WRN] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is higher than the warning threshold of 75%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Empty Values - Should pass\n[LOG] Executing: bash entrypoint.sh   \n[LOG] Output:\n\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Getting disk usage ...\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage for the path \"/\" is 54%\n[INF] 1625941680 Sat Jul 10 18:28:00 UTC 2021 :: Disk usage is lower than the warning threshold of 85%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Logging level - OFF - Should pass\n[LOG] Executing: bash entrypoint.sh\n[LOG] Output:\n\n\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Logging level - Debugging - Should pass\n[LOG] Executing: bash entrypoint.sh / 75 92\n[LOG] Output:\n\n[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Getting disk usage ...\n[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Finished getting disk usage 92 with the given path /\n[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Warning threshold is 75\n[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage for the path \"/\" is 92%\n[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%\n[DBG] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Successfully completed disk usage process\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Logging level - Warning - Should pass\n[LOG] Executing: bash entrypoint.sh / 75 92\n[LOG] Output:\n\n[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%\n\n[LOG] Test passed as expected\n-------------------------------------------------------\n[LOG] Logging level - Unknown - Should fail\n[LOG] Executing: bash entrypoint.sh / 75 92\n[LOG] Output:\n\n[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\n\n[LOG] Test failed as expected\n-------------------------------------------------------\n[LOG] Unknown inline logging level - Should fail\n[LOG] Executing: bash entrypoint.sh / 75 92\n[LOG] Output:\n\n[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Getting disk usage ...\n[INF] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage for the path \"/\" is 92%\n[WRN] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: Disk usage is higher than the warning threshold of 75%\n[ERR] 1625941681 Sat Jul 10 18:28:01 UTC 2021 :: [EXIT_CODE=2] The argument \"WONKA\" does not exist in INF OFF WRN DBG\n\n[LOG] Test failed as expected\n```\n\u003c!-- replacer_end_tests --\u003e\n\n\u003c/details\u003e\n\n## Advanced Bash Expressions\n\nIn the following section you'll find documenation about the advanced Bash expressions that I used in this project.\n\n### Piping the data\n\nUsing `|` to pipe the data and getting the fifth element of the final line (Milla Jovovich? Bruce Willis?)\n```bash\nget last line | squash spaces     | split string by \" \" and get the Fifth Element \ntail -1       | tr -s \"[:space:]\" | cut -d\" \" -f5\n```\n\nThis expression is used in the code in\n\n```bash\npath=\"/\" # pseudo code\nusage_msg=\"$(df -h \"$path\")\"\necho -e \"$usage_msg\" # print temporary variable, including line breaks `-e`\npercentage_msg=\"$(echo \"$usage_msg\" | tail -1 | tr -s \"[:space:]\" | cut -d\" \" -f5)\"\necho \"$percentage_msg\" # print results\n```\n\n```bash\n# Output - varies per machine\n6%\n```\n\n### Associative Array Keys As Array\n\nTo get Keys  of a given associative array, use the `!` character.\n\n```bash \ndeclare -A ASSOCIATIVE_ARRAY=([FIRST]=1 [SECOND]=2) \u0026\u0026 \\\necho ${!ASSOCIATIVE_ARRAY[*]} \u0026\u0026 \\\ndeclare -a KEYS_ARRAY=(\"${!ASSOCIATIVE_ARRAY[*]}\") \u0026\u0026 \\\necho \"Keys Array: ${KEYS_ARRAY[@]}\"\n```\n\n```bash\n# Output\nFIRST SECOND\nKeys Array: FIRST SECOND\n```\n\nThis expression is used in the code in - `${!_LOGGING_LEVELS[*]}`\n\n\n### Initializing Variables\n\n1. Use the first argument `$1` as the default value; if empty, use the var `$DISK_USAGE_PATH`\n\n   ```bash\n   _DISK_USAGE_PATH=\"${1:-\"$DISK_USAGE_PATH\"}\"\n   ```\n\n1. Check if default value is set, if not, set to `/`\n   ```bash\n   _DISK_USAGE_PATH=\"${_DISK_USAGE_PATH:-\"/\"}\"\n   ```\n\n### Substring\n\nReplace all `%` instances with `\"\"` - The chars `//` after `MY_VAR` stands for \"all instances\"; when using a single `/` it removes the first instance only\n```bash\n${MY_VAR//replace_this/with_this}\n```\n\nThis expression is used in the code in\n\n```bash\npercentage_msg=\"$(echo \"$usage_msg\" | tail -1 | tr -s \"[:space:]\" | cut -d\" \" -f5)\" # pseudo code\npercentage=\"${percentage_msg//%/}\"\necho \"$percentage\"\n```\n\n```bash\n# Output - varies per machine\n6\n```\n\n### Datetime\n\n```bash\n$(date +%s) # DDD MMM DD HH:MM:SS TZ YYYY\n$(date)     # 1234567890 unix timestamp\n```\n\n## Contributing\n\nReport issues/questions/feature requests on the [Issues](https://github.com/unfor19/bash-logging/issues) section.\n\nPull requests are welcome! These are the steps:\n\n1. Fork this repo\n1. Create your feature branch from master (`git checkout -b my-new-feature`)\n1. Add the code of your new feature\n1. Run tests on your code, feel free to add more tests\n   ```bash\n   $ bash tests.sh\n   ... # All good? Move on to the next step\n   ```\n1. Commit your remarkable changes (`git commit -am 'Added new feature'`)\n1. Push to the branch (`git push --set-up-stream origin my-new-feature`)\n1. Create a new Pull Request and provide details about your changes\n\n## References\n\n1. [Simple logging levels in Bash](https://stackoverflow.com/a/48087251/5285732)\n2. [Create timestamp variable in bash script](https://stackoverflow.com/questions/17066250/create-timestamp-variable-in-bash-script)\n\n## Authors\n\nCreated and maintained by [Meir Gabay](https://github.com/unfor19)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](https://github.com/unfor19/bash-logging/blob/master/LICENSE) file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funfor19%2Fbash-logging","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funfor19%2Fbash-logging","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funfor19%2Fbash-logging/lists"}