log4sh version 1.4.2

A list of contributors to log4sh can be found in the source archive as doc/contributors.txt. I want to personally thank all those who have contributed to make this a better tool.

Feedback is most certainly welcome for this document. Send your additions, comments and criticisms to the following email address: <kate.ward@forestent.com>.

To preconfigure log4sh, create a properties file (see the Properties File later in this document). If the properties file is not located in the same directory as log4sh, set the LOG4SH_CONFIGURATION environment variable to the full path to the properties file. If you do not wish to preconfigure log4sh, please read the Configure log4sh in code section later in this chapter.

To source the code into your script (also known as including), one uses the sourcing ability of shell to source one script into another. See the following quick example for how easy this is done.

#! /bin/sh

# source log4sh from current directory
. ./log4sh

Here is some sample code that looks for log4sh in the same directory as the script is located, as well as the current directory. If log4sh could not be found, it exits with an error. If log4sh is found, it is loaded, along with the log4sh.properties file in the current directory (see the following example). It then logs a message at the INFO level to STDOUT.

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

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

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

Here is the log4sh.properties file for the previous example. Save it in the same directory you are running the above script from.

#
# log4sh example: Hello, world properties file
#

# Set root logger level to INFO 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=%-4r [%t] %-5p %c %x - %m%n

If log4sh was not preconfigured, the default configuration will be equivalent the config shown below.

Note: log4sh will complain if no configuration file was specified or found. If you meant for the default configuration to be used, or you want to configure log4sh via code, make sure to define the LOG4SH_CONFIGURATION with the value of 'none'.

log4sh.rootLogger=ERROR, stdout
log4sh.appender.stdout=ConsoleAppender
log4sh.appender.stdout.layout=PatternLayout
log4sh.appender.stdout.layout.ConversionPattern=%-4r [%t] %-5p %c %x - %m%n

To configure log4sh in code, simply call the appropriate functions in your code. The following code sample loads log4sh from the current directory, configures it for STDERR output, and the logs a message at the INFO level.

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

# load log4sh (disabling properties file warning) and clear the default
# configuration
LOG4SH_CONFIGURATION='none' . ./log4sh
log4sh_resetConfiguration

# set the global logging level to INFO
logger_setLevel INFO

# add and configure a FileAppender that outputs to STDERR, and activate the
# configuration
logger_addAppender stderr
appender_setType stderr FileAppender
appender_file_setFile stderr STDERR
appender_activateOptions stderr

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

Once log4sh is loaded, logging is as simple as calling the appropriate logging function with a message to be logged. Take a look at the above examples to see just how easy it was to log the statement "Hello, world" at an INFO level.

The samples above show the standard way of logging a message via log4sh. That standard method is by calling the appropriate function, and passing the message as a parameter.

logger_info 'message to log'

There is a second way of logging as well. The second method is via pipes. What this method is really good for is logging the standard output (STDOUT) of a command to the logfile. Piping echo statements is a bit silly, but something like piping the output of a ls is more practical (e.g. ls -l |logger_info).

echo 'message to log' |logger_info

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
    

There are some environment variables that can be used to pre-configure log4sh, or to change some of its default behavior. These variables should be set before log4sh is sourced so that they are immediately available to log4sh.

Here is the full list of supported variables.

LOG4SH_CONFIGURATION='/path/to/log4j.properties'

LOG4SH_CONFIG_PREFIX='log4j'

There are several environment variables that can be set to alter the behavior of log4sh. The full listing is below.

Logging to a remote syslog host is incredibly easy with log4sh, but it is not functionality that is normally exposed to a shell user. The logger command, which is used for local syslog logging, unfortunately does not support logging to a remote syslog host. As such, a couple of choices are available to enable logging to remote hosts.

Choice #1 -- reconfigure the syslogd daemon

One can alter the configuration of the local syslog daemon, and request that certain types of logging information be sent to remote hosts. This choice requires no extra software to be installed on the machine, but it does require a reconfiguration of the system-wide syslog daemon. As the syslog daemon is different between operating systems, and even between OS releases, no attempt will be made to describe how to do this in this document. Read the respective man page for your particular system to learn what is required.

Choice #2 -- install nc (netcat) command -- recommended

The nc (netcat) command has the ability to generate the UDP packet to port 514 that is required for remote syslog logging. If you have this command installed, you can tell log4sh that this alternative command exists, and then you will be able to use the appender_syslog_setHost() function as you would expect.

The examples below show what a minimum properties file or a minimum script should look like that do remote syslog logging.

#
# log4sh example: remote syslog logging
#

# Set the 'nc' alternative command to enable remote syslog logging
log4sh.alternative.nc = /bin/nc

 Set root logger level to INFO and its only appender to mySyslog
log4sh.rootLogger=INFO, mySyslog

# mySyslog is set to be a SyslogAppender.
log4sh.appender.mySyslog = SyslogAppender
log4sh.appender.mySyslog.SyslogHost = somehost

#! /bin/sh
#
# log4sh example: remote syslog logging
#

# load log4sh (disabling properties file warning) and clear the default
# configuration
LOG4SH_CONFIGURATION='none' . ./log4sh
log4sh_resetConfiguration

# set alternative 'nc' command
log4sh_setAlternative nc /bin/nc

# add and configure a SyslogAppender that logs to a remote host
logger_addAppender mySyslog
appender_setType mySyslog SyslogAppender
appender_syslog_setFacility mySyslog local4
appender_syslog_setHost mySyslog somehost
appender_activateOptions mySyslog

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

Logging is great, but not when it runs you out of hard drive space. To help prevent such situations, log4sh has automated file rolling built in. By changing your FileAppender into a RollingFileAppender, you enable automatic rolling of your log files. Each logfile will be rolled after it reaches a maximum file size that you determine, and you can also decide the number of backups to be kept.

To limit the maximum size of your log files, you need to set the MaxFileSize appender option in a properties file, or use the appender_file_setMaxFileSize() function. The maximum size is specified by giving a value and a unit for that value (e.g. a 1 megabyte log file can be specified as '1MiB', '1024KiB', or '1048576B'). Note, the unit must be specified with the proper case, i.e. a unit of 'KB' is correct 'kb' is not.

The default maximum file size is equavilent to 1MiB

Note: log4sh differes from log4j in the impretation of its units. log4j assumes that all units are base-2 units (i.e. that KB = 1024B), where as log4sh makes a distinction between the standard SI units of KB (base-10 ~ 1000B = 10^3) and KiB (base-2 ~ 1024B = 2^10). If this causes problems, call the log4sh_enableStrictBehavior() once after loading log4sh to force the unit intrepretation to be like log4j.

To limit the maximum number of backup files kept, you need to set the MaxBackupIndex appender option in a properties file, or use the appender_file_setMaxBackupIndex() function. Whenever a file has reached the point of needing rotation, log4sh will rename the current logfile to include an extension of '.0', and any other backups will have thier extension number increased as well. With a maximum backup index of zero, no backups will be kept.

The default maximum backup index is equavilent to '1 MiB'

#
# log4sh example: using the RollingFileAppender
#

 Set root logger level to INFO and its only appender to R
log4sh.rootLogger=INFO, R

# add a RollingFileAppender named R
log4sh.appender.R = RollingFileAppender
log4sh.appender.R.File = /path/to/some/file
log4sh.appender.R.MaxFileSize = 10KB
log4sh.appender.R.MaxBackupIndex = 1

#! /bin/sh
#
# log4sh example: using the RollingFileAppender
#

# load log4sh (disabling properties file warning) and clear the default
# configuration
LOG4SH_CONFIGURATION='none' . ./log4sh
log4sh_resetConfiguration

# add and configure a RollingFileAppender named R
logger_addAppender R
appender_setType R RollingFileAppender
appender_file_setFile R '/path/to/some/file'
appender_file_setMaxFileSize R 10KB
appender_file_setMaxBackupIndex R 1
appender_activateOptions R

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