KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #claude-code #codex #dsh #dsh-plugin #ai-agent #ai-agents #deepseek-harness #agent-skills #macos #cli

bashlog

★ 94 Open GitHub ↗

A simple but powerful logging library for bash

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# bashlog

A simple but powerful logging library for bash

## Simple Usage

Place log.sh in the directory with your bash script(s)

Add `. log.sh` to the top of your script(s)

Add logging lines with level info, warn, error or debug, for example:

* `log info 'My info message';`

* `log warn 'My warning message';`

* `log error 'My error message';`

* `log debug 'My debugging message';`

## Bash Shell Options

This library sets the following shell options:

`set -uo pipefail`

This is a recommended default for any scripts you write:
  * You should not use unbound variables (-u)
  * You should ensure pipelines fail if any of the commands in the pipeline fail (-o pipefail)

This library does _not_ `set -e` because automatically exiting a script
when any error is encountered is lazy and a poor user experience.
Errors should be caught and handled by your scripts.
This can be supported by the use of this library's 'error' log-level.

If you do not like these settings - change them or remove them.

## Debugging

To enable debugging, set `DEBUG=1` in your script's environment.

* When `DEBUG=0`, log lines with level 'debug' are not printed.
  * When `DEBUG=1`, log lines with level 'debug' are printed.

### Interactive debugging of errors

When debugging is enabled, error messages are followed by an interactive
bash shell from which debugging can take place.

When debugging activity is complete: exiting the shell with code 0
will allow the rest of your script to continue, exiting the shell
with a non-zero code will cause your script to terminate with the
same non-zero code.

### Bash Debug Trap

This library enables a bash DEBUG trap, that provides you with
a variable called `prev_cmd` to help you write simple and useful
debug logging messages.

For example:

```
my_command --with very -c -o -m -p -l -e -x -- parameters \
  && log debug "${prev_cmd}" \
  || log error "${prev_cmd};
```

This will log the exact command that was executed as a debug log
(only when `DEBUG=1`).

If the command fails, the error message will show the precise command
that failed, and when `DEBUG=1` will then present you with a debug
shell from which you can choose to continue or to exit your script.

#### Advanced Debugging

This library contains an alternate debug trap that can be uncommented
which will log a debug log entry (when `DEBUG=1`) for every single
command that is executed throughout your script.

Enabling this alternate trap will severely impact performance of
your script, and the bashlog testing suite will not be applicable.

## File, JSON & Syslog

When instructed, the logging library can also log output:
  * To a file in plain text format: `BASHLOG_FILE=1`
  * To a file in JSON format: `BASHLOG_JSON=1`
  * To Syslog: `BASHLOG_SYSLOG=1`

## Additional environment variables

### BASHLOG_DATE_FORMAT

Default: `+%F %T`

The date format to use for stdout and file logging (passed to the `date` binary).

Syslog date format is determined by syslog configuration.

JSON date format is epoch.

### BASHLOG_FILE_PATH

Default: `/tmp/$(basename {0}).log`

When `BASHLOG_FILE=1`, logs are written to the file at `$BASHLOG_FILE_PATH`

This defaults to the name of your script (the one from which you sourced this library),
with a `.log` suffix, in the /tmp directory.

e.g. yourscript.sh will produce `/tmp/yourscript.sh.log`

### BASHLOG_JSON_PATH

Default: `/tmp/$(basename {0}).log.json`

When `BASHLOG_JSON=1`, logs are written in JSON format to the file at `$BASHLOG_JSON_PATH`

This defaults to the name of your script (the one from which you sourced this library),
with a `.log.json` suffix, in the /tmp directory.

e.g. yourscript.sh will produce `/tmp/yourscript.sh.log.json`

### BASHLOG_SYSLOG_FACILITY

Default: `local0`

When `BASHLOG_SYSLOG=1`, logs are written to Syslog.

This determines the syslog facility to use (local0 <-> local7)

### BASHLOG_SYSLOG_TAG

Default: `$(basename {0})`

When BASHLOG_SYSLOG=1, logs are written to Syslog.

This determines the syslog tag to use, defaulting to the name of your script,
e.g. `yourscript.sh`

## Recommended Usage

```
. log.sh;

cat << 'EOF' > /etc/yum.repos.d/smoo.repo &&
[smoo]
name=smoo
baseurl=file:///tmp/smoo/
enabled=1
gpgcheck=0
EOF
  log debug "Smoo repo yum repository configuration written successfully" \
  || log error "Failed to write smoo repo yum repository configuration";

# Install the smoo agent
yum -y install smoo-agent \
  && log info "smoo-agent RPM installed successfully" \
  || log error "Failed to install smoo-agent RPM";

# Change into the newly installed repository
cd /srv/smoo \
  && log debug "${prev_cmd}" \
  || log error "${prev_cmd}";

/opt/smoo-agent/bin/tests /srv/smoo \
  && log info "Smoo Tests Succeeded" \
  || log error "Smoo Tests Failed";

# Execute the smoo-agent
/opt/smoo-agent/bin/smoo \
  -r \
  --config config.json \
  --log_level "info" \
  && log info "Smoo Agent execution completed successfully" \
  || log error "Smoo Agent execution failed!";

if [ "${DEBUG:-0}" -eq "1" ]; then
  log debug "Entering end-of-script debug shell. Exit shell to continue.";
  /bin/bash;
fi;

log info 'Smoo Agent control finished';

exit 0;
```

## Testing

A full test suite is provided alongside the bashlog library in `test.sh`.

The test suite itself has been tested on Slackware Linux. If your syslog
configuration behaves differently to the default in Slackware, the test
suite may fail. Feel free to provide feedback / pull requests to improve it.

The test suite requires sudo privileges in order to create files that
cannot then be accessed. I could replace this with non-root privilege
modification - and maybe I will - but not today.

### Interactive Testing

If you pass `TEST_INTERACTIVE=1` to test.sh, the automated tests will be
followed by interactive tests which test the debug shell mechanisms.

User input is required, following instructional prompts in order to
properly validate the functionality.

bashlog

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README