Bash Logger

A flexible, reusable logging module for Bash scripts that provides standardized logging functionality with various configuration options.

Note

This is a expansion of the originally published bash_logging GitHub gist published by @GingerGraham.

Primary artifact

The core deliverable of this repository is logging.sh. It is intentionally kept as a single, self-contained (and yes, long) Bash file so you can drop it next to your scripts and source it without any packaging steps. Everything else in the repo - docs, demos, and pipeline scripts - exists to support using that file.

Features

• Standard syslog log levels (DEBUG, INFO, WARN, ERROR, CRITICAL, etc.)
• Console output with color-coding by severity
• Configurable stdout/stderr output stream split
• Optional file output
• Optional systemd journal logging
• Customizable log format
• UTC or local time support
• INI configuration file support
• Runtime configuration changes
• Special handling for sensitive data
• Secure-by-default newline sanitization to prevent log injection
• Secure-by-default ANSI code stripping to prevent terminal manipulation attacks
• Configurable log line length limits for DoS resistance
• TOCTOU race condition protection during log file creation

Quick Start

# Source the logging module
source /path/to/logging.sh

# Initialize the logger
init_logger

# Log messages
log_info "Application started"
log_error "Something went wrong"

See Getting Started for detailed installation and basic usage instructions.

Documentation

Core Documentation

• Getting Started - Installation and basic usage
• Log Levels - Understanding severity levels
• Initialization - Configuring the logger at startup
• Configuration - Using configuration files

Advanced Topics

• Output Streams - Controlling stdout/stderr behavior
• Formatting - Customizing log message format
• Journal Logging - Integration with systemd journal
• Runtime Configuration - Changing settings on the fly
• Sensitive Data - Handling sensitive information securely

Reference

• API Reference - Complete function reference
• Examples - Comprehensive usage examples
• Troubleshooting - Common issues and solutions

Common Use Cases

Basic Script Logging

source /path/to/logging.sh
init_logger
log_info "Script starting"

See: Getting Started

Logging to File

init_logger --log "/var/log/myapp.log" --level INFO

See: Initialization

Using Configuration Files

init_logger --config /etc/myapp/logging.conf

See: Configuration

Journal Integration

init_logger --journal --tag "myapp"

See: Journal Logging

Testing

The project includes a comprehensive test suite to verify all functionality. To run the tests:

make test
# Or directly:
cd tests && ./run_tests.sh

Additional testing tools are available via the Makefile:

make coverage        # Run tests with kcov code coverage
make test-junit      # Generate JUnit XML report
make sonar-analysis  # Full coverage + SonarQube analysis

Note: Coverage and SonarQube targets require additional tools (kcov, sonar-scanner). See Testing Documentation for setup details.

See tests/README.md and Testing for more information.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

The project uses pre-commit hooks for code quality checks (ShellCheck, MarkdownLint, etc.). The CI lint workflow runs these same hooks, so tool versions are centralized in .pre-commit-config.yaml. See docs/PRE-COMMIT.md for setup instructions.

Maintainers

This project is currently maintained by @GingerGraham.

License

This module is provided under the MIT License.