Usage of rsh-logging

Using rsh-logging is straight-forward, and as a result, so is using logging. Below are some typical examples along with explanations.

Standard Usage in Code

Most logging packages assume you will get a logger per class and then cache that logger within a static class variable. This allows any code within the class to be turned on via logging settings, and it keeps initialization overhead to a minimum. A typical example would look like the following:

private static final Log logger = LoggingUtil.getLogger(YourClass.class);

Alternatively, you can use the fully qualified class name:

private static final Log logger = LoggingUtil.getLogger("you.package.YourClass");

It is recommended that you use the YourClass.class notation where possible, as it will minimize typos and errors. An Eclipse template can help a lot with this:

private static final Log logger = LoggingUtil.getLogger(${enclosing_type}.class);

If you map this to "logger", ctrl+space (or whatever you have completion mapped to) will then automatically insert the above line, inserting your class name for you in place of "${enclosing_type}".

Using with "Fine-Grained" Debugging in Code

The standard usage allows you to log anywhere within a class--but all logging is turned on or off at the class level. If you wanted to be more fine-grained than that, you can use the getLogger(String) method to give you loggers that are "nested" within the class name-space:

public class YourClass {
    public void someMethod() {
        Log logger = LoggingUtil.getLogger("you.package.YourClass.someMethod");
        ...
    }
}

This would then allow you to fine-tune your logging. You could then set you.package.YourClass.level=debug and you.package.YourClass.someMethod=info, allowing you to turn off a noisy method that rarely needs to be turned on fully.

What you choose for a name doesn't even have to correspond to a class or a method. So you could just as easily have said:

public class YourClass {
    public void someMethod() {
        Log logger = LoggingUtil.getLogger("you.package.someFunctionalCategory");
        ...
    }

    public void someRelatedMethod() {
        Log logger = LoggingUtil.getLogger("you.package.someFunctionalCategory");
        ...
    }
}

And then both methods would be tied to the namespace "you.package.someFunctionalCategory" instead of the enclosing type.

PLEASE NOTE: This kind of logging classification and leveling is rarely needed. It is recommended you just stick to class level loggers and make sure to group classes and functionality in similar packages and types to allow easier logging configuration.

Turning on Debugging Through the Environment

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:

Setting Default Settings Through 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.

NOTE: The environment settings always trump the rshlogging.properties file. So if you set your.package.YourClass.level=trace in your rshlogging.properties file, it can be overridden by setting -Dyour.package.YourClass.level=info in the environment.