Configuration of rsh-logging

This section explains rsh-logging configuration and how it works.

The Easy Answer: VM Settings

Usually you just want to turn on debugging while testing or while debugging an app. You can do this by setting VM variables when you start your application or test.

-Dyour.package.YourClass.level=trace

The above supplied to a VM will tell the logging package to turn on the maximum amount of logging for just the your.package.YourClass logging statements. All others will remain at their defaults (usually "info"). If you were using a command line application, you would just use the following:

java -Dyour.package.YourClass.level=trace your.package.Application

You can usually set VM switches in the "run" or "test" dialog of your IDE. In Eclipse, choose Run -> Run... and it will bring up the Run profiles for all the applications and tests you have executed lately. Just click on the "Arguments" tab and then place the switch, as written in the first example in the "VM arguments" window:

Using Configuration Files

If you add the a file called "rshlogging.properties", it will be read by the rsh-logging package and used to setup logging levels (amongst other things). So, if you place the following in your classpath:

rshlogging.properties:
your.package.YourClass.level=trace

The logger for your.package.YourClass will always be set to trace.

Set defaults in files with care. The default of info is usually just fine. You should allow users of your software to set the defaults beyond info.

Order of Processing For Sources

There are several sources consulted when rsh-logging configures the underlying toolkit or framework. They are processed, in order from lowest precedence to highest, as follows:

1. System-wide Defaults (if any)
2. rshlogging-default.properties
3. rshlogging.properties
4. ConfigurationSource objects
5. System Environment [trumps all previous sources]

The system-wide defaults are processed first. For the JDK Logging package, this is the logging.properties file contained in the JRE. For Log4J this would be the log4j.properties file.

The rshlogging-default.properties defines some defaults that usually make logging "usable". For instance, in the case of the JDK logger, it enables automatically setting the Console to the lowest level set in the system (allowing debugging messages to show up if they are enabled somewhere). You usually do not need to worry about (or know about) this file or its contents.

The rshlogging.properties is intended to be included with an application by default. If you have special logging settings you need set when deploying an application, you can set them here. This is also where to setup what kind of logging formatters you want used, etc.

The rsh-logging ConfigurationSource objects are intended to allow you to dynamically inject logging settings before the logging system is initialized. This allows you to read rsh-logging compliant settings from any source you want to or even create them on the fly.

Finally, the environment (i.e. System.getProperties()) is searched for any relevant logging properties (such as the ConsoleHandler for the JDK Logger) or any property names ending in ".level". These settings override any previous settings found in the system.

After all the settings have been parsed and stacked in order of precedence, the resulting union is then passed on to the logging toolkit. The union of settings may be used entirely, or it may be punched in piece-meal depending on the surrounding environment. For instance, in a stand alone application, using the settings as the entire configuration is usually just fine. However, within Tomcat or some other similar application server that already has logging set up for its own use, wiping out the configuration setting and using the union of settings is not acceptable (it just flat-out breaks). In such cases, new logging levels are punched into the already initialized system one at a time, preserving any application-server-wide settings while accomodating the new settings.

Configuration Only Happens Once

Whatever the path configuration takes, it happens only once at the beginning the application's life-cycle. You don't need to worry about configuration or its overhead, since it will happen only upon initialization--and because it is usually neglegible in impact.

The configuration information is stored using a SoftReference. This means that in the case of most J2EE container's, you application's logging information will be reloaded when the application is reloaded. This assumes you are not using rsh-logging from the server's classpath. If you are, logging configuration happens only once per life-cycle of the server (that is, you need to restart the server to get new logging settings to apply).