log4sh

Log4sh has been developed under the Bourne Again Shell (bash) on Linux, but great care has been taken to make sure it works under the default Bourne Shell of Solaris (sh) as this happens to be the primary platform used by myself.

To get started quickly with log4sh, take a look at the test-log4sh sample script in the src/test directory of the distribution. You will need to copy the log4sh script itself from the src/shell directory into the test directory before running the test. This test script is designed to configure log4sh via code. Later on, we will configure log4sh with a properties file, very similar to how log4j is configured.

By default, log4sh is configured with a ConsoleAppender which logs to STDOUT using a SimpleLayout and a logging level of ERROR. If no configuration file is found, a warning message will be given letting the user know that no configuration file was found. This warning can be supressed by setting the LOG4SH_CONFIGURATION environment variable to none.

Run the first test.

$ ./test-log4sh

After a first run you will see quite a bit of output to the display, and as well two log files will be created (log4sh-pattern.log and log4sh-simple.log). The display contains a mix of output to STDOUT and STDERR, and the files contain various versions of the same data, but with output that changes as various layouts and patterns are tested. To clean up the display a bit, you could send all of the output of the STDERR appender off to /dev/null.

Run the test again, but redirecting STDERR to /dev/null.

$ ./test-log4sh 2>/dev/null

Go ahead a take a look at the test script to get a feel of what the script is trying to accomplish. Hopefully, you can see just how simple log4sh is to use and control.

For our next test, we will configure log4sh with a properties file. This test is incredibly simple as it is designed to show the power of the properties file. Copy first example properties file log4sh.properties.ex1 from the src/examples directory into the test directory, and give it the name log4sh.properties.

Run the second test.

$ ./test-properties

This test is designed to look very much like one of the log4j examples. The properties file is taken almost verbatum from the log4j short manual, with only small changes required to make it work for log4sh. Log4sh is configured with a ConsoleAppender that has a PatternLayout. One limitation of log4sh is that it does not have access to a timer with millisecond accuracy, so it logs only with an accuracy of one second. For most situations, this should be sufficient.

Copy the second example properties file (log4sh.properties.ex2) as log4sh.properties, and rerun the test. This second properties file is only slightly different from the first in that it adds the filename to the output, and removes the %x pattern directive as that directive is not supported by log4sh.

The next example shows a typical situation where an administrator wants to run a script via a cron job, wants a log of the scripts actions, but only wants an email if the job failed.

Copy the third example properies file (log4sh.properties.ex3) over, and rerun the test. This time, the output will be sent to two separate locations; STDERR and a file called example.log. The output to STDERR is set to the ERROR level, and output sent to the file is at the INFO level. More output is written to the logfile (as expected) when the test is run.

In the situation of being run from a cron job, the logfile will always be written, but an email comes only when output from the script came at the ERROR or FATAL level. An administrator can even configure the log4sh.properties file to a DEBUG level so that more output is logged for testing or debugging purposes, and this change can happen without making any code changes to the script. Something very useful in a production environment!

The usage of log4sh is simple. There are only a few simple steps required to setup and use log4sh in your application.

#! /bin/sh

# source log4sh from current directory
. ./log4sh

#! /bin/sh
#
# log4sh example: Hello, world
#
myDir=`dirname $0`

# find and source log4sh
if [ -r "$myDir/log4sh" ]; then
  dir=$myDir
elif [ -r "./log4sh" ]; then
  dir=.
else
  echo "fatal: could not find log4sh" >&2
  exit 1
fi
. $dir/log4sh

# say Hello to the world
logger_info "Hello, world"

#
# log4sh example: Hello, world properties file
#

# Set root logger level to DEBUG and its only appender to A1
log4sh.rootLogger=INFO, A1

# A1 is set to be a ConsoleAppender.
log4sh.appender.A1=ConsoleAppender

# A1 uses a PatternLayout.
log4sh.appender.A1.layout=PatternLayout
log4sh.appender.A1.layout.ConversionPattern=%r [%t] %p %c %x - %m%n

#! /bin/sh
#
# log4sh example: Hello, world
#

# source log4sh (disabling properties file warning)
LOG4SH_CONFIGURATION="none" . ./log4sh

# configure log4sh defaults
logger_setLevel INFO

# configure appenders
appender_setAppend stdout false
logger_addAppender stderr
appender_setAppenderType stderr FileAppender
appender_setAppenderFile stderr STDERR

# say Hello to the world
logger_info "Hello, world"

Log4sh can be configured with a properties file that is separate from the actual script where the logging takes place. By default, log4sh looks for its properties file called log4sh.properties in the current directory. If the file is located elsewhere or with a different name, log4sh can be configured by setting the LOG4SH_CONFIGURATION environment variable (eg. LOG4SH_CONFIGURATION="/etc/log4sh.conf").

A log4sh.properties file that is completly empty is sufficient to configure log4sh. There will be absolutely no output however (which might just be what is desired). Usually though, some output is desired, so there is at least a recommended minimum configuration file. An explaination of the file follows the example.

log4sh.rootLogger=INFO, stdout
log4sh.appender.stdout=ConsoleAppender

In the first line, the root logger is configured by setting the default logging level, and defining the name of an appender. In the second line, the stdout appender is defined as a ConsoleAppender.

  log4sh.appender.A1=FileAppender
  

  log4sh.appender.A1.File=output.log
  

  log4sh.appender.A1.layout=PatternLayout
  

  log4sh.appender.A1.layout.ConversionPattern=%d [%p] %c - %m%n
  

Log4sh has been completly developed from scratch by myself, Kate Ward. I use it in production environments where logging from shell scripts is critical, and where I need more than just a simple "Hello, I worked" type of logging message. If you like what you see, or have any suggestions on improvements, please feel free to drop me an email at <kate.ward@forestent.com>. If there is enough interest in the project, I will develop it further.

Log4sh is licensed under the GNU Lesser Public License. The contents and copyright of this site and all provided source code are owned by Kate Ward.