Simple Log User Guide

Simple Log - Quick Start

Welcome to Simple Log.
Seeing as this is a Quick Start, I'll try to keep the text to an absolute minumum. This document should describe enough about Simple Log for you to:

Download Simple Log
Get it in your classpath
Use it in your code
Deploy a configuration file
See some output
Change the debug and trace levels
Output to a file
Find other information

If anything in this document is wrong, please let me know by posting an issue on GitHub

What to download

If you haven't already downloaded Simple Log, go to the Downloads page and get the latest 'Full Release'.

Unzip it into a place where you keep all your Java libraries. I put mine under C:\Java\lib\. All files in the zip are under a subdirectory, so you don't need to create a directory to unzip into.

Which JARs to Use

You'll definitely want simple-log.jar in your classpath. If you want log rolling, you'll also need simple-log-rollover.jar. You'll find both of these in the main directory of the release.

If you are planning to use Simple Log as a provider for either Commons Logging or SLF4J, you will find additional JARs under the adapters/ directory that you'll need to use.

Which Files to Use

Simple Log also needs configuration files to make it do anything useful. All the configuration files you need are provided with Simple Log and you simply need to copy them and change them to suit your needs.

You'll definitely want simplelog.properties and simplelog-config.properties. If you want log rolling, you'll also need simplelog-rollover.properties. All these files are in the properties/ directory of the release.

Where to put the JARs

I recommend putting the Simple Log JARs in your application classpath. If you are using a web or application user, I suggest putting the JARs in your WEB-INF/lib or APP-INF/lib directory.

A guy once put the JARs in lib/ext under his JRE and we spent a few hours and countless emails between us trying to figure out why it wouldn't load his configuration files. To summarise it real quick, Simple Log, by default, loads the configuration files from the classpath, and if you put the JARs in a ClassLoader that is higher in the hierarchy than the ClassLoader that the configuration files are in, you're going to have trouble. If that doesn't make sense to you, you probably need to do a bit more study on class loading.
Articles about Class Loading
Google for Class Loading tutorials

Where to put the configuration

Put simplelog.properties and simplelog-config.properties in the root of your classpath. simplelog-rollover.properties goes here too if you're using log rolling.

By 'root of you classpath', I mean this: If you specify to your application:

java -cp C:\myapplication\classes org.grlea.application.MyApplication

and under that span class="filePath" directory you have other subdirectories like this:

C:\myapplication\classes\org\grlea\application

then you want to put the configuration files in:

C:\myapplication\classes\

To word it another way, you need to put the configuration files in a directory that is itself on the classpath, not a directory this is under a directory that is on the classpath.

If you're using an IDE, you'll probably want to put your configuration files at the root of your source tree and instruct the IDE to copy them over to the classes directory on compilation.

If you're going to use Simple Log in a web application, it's best to place your configuration files in the WEB-INF/classes directory, or in APP-INF/classes for an application server. You'll probably also want to enable reloading, allowing you to change the configuration without restarting your server.

How to use Simple Log in Code

The normal way to use Simple Log from within your code is to create an instance of a SimpleLogger at the start of each class like this:

private static final SimpleLogger log = new SimpleLogger(HelloWorld.class);

and then to use that logger throughout your class, like this:

public class
SimpleLogTest
{
   private static final SimpleLogger log = new SimpleLogger(SimpleLogTest.class);

   public static void
   main(String[] argv)
   {
      log.entry("main");
      log.info("This is a test of Simple Log.");
      log.debugObject("argv", argv);
      log.exit("main");
   }
}

Try It Out!

If you copy the above code into your workspace, compile it, and run it with the Simple Log JARs and configuration files in the right place, you should see output very similar to the following:

Mon 2006/05/01 20:34:01.243|   |main|SimpleLogTest|This is a test of Simple Log.

If you don't see anything, you've most likely put the configuration files in the wrong place. Either that, or you've already been playing with your configuration and you're outputting to a file and not to the console.

What to log at each level

Simple Log has seven levels at which information can be logged. The levels are:

Fatal
Error
Warn
Info
Debug
Verbose
Ludicrous (the level you've always wanted but were always afraid to ask for)

It's obviously best if everyone working on a project, if not everyone in the world, is using each level for similar types of information. To this end, each instance in the DebugLevel class is documented so as to make it pretty clear what kind of information should be logged at that level.

The tracing functionality, which is used to log entry to and exit from methods, is configured independently of the debug levels.

How to set debug levels

Debug levels are set by creating a property in the simplelog.properties configuration file with the property name beng a class or package and the property value being either the name (e.g. Verbose) or number (e.g. 6) of the Debug Level to which that logger should be set.

For example, if you executed the example SimpleLogTest class before and you got the output happening, you can now open up the simplelog.properties file and enter this line at the end of it:

SimpleLogTest = verbose

If you run the program again, you should see output like this:

Mon 2006/05/01 21:08:06.894|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:08:06.904|---|main|SimpleLogTest|argv|[]

If you pass some arguments to the program, like this:

java -cp .;C:\Java\lib\simple-log\2.0\simple-log.jar SimpleLogTest Testing debug of object array

you'll see output like this:

Mon 2006/05/01 21:08:06.894|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:08:06.904|---|main|SimpleLogTest|argv|[Testing, debug, of, object, array]

Congratulations!
You just logged an object! You should do more of that. It's one of the most useful things you can put in your log, and Simple Log makes it really easy to do.

Note that we only didn't use the package name of this class because it doesn't have one. If it were in a package, we would need to use the fully-qualified name to configure it.

How to set trace flags

Tracing is configured using 'trace flags', and setting these is almost identical to setting debug levels. The main differences are that you need to put #trace at the end of the class or package name, and the value is either true or false.

So, if you now added this line to the end of your simplelog.properties:

SimpleLogTest#trace = true

and re-run that program again, you should see this:

Mon 2006/05/01 21:13:31.111|>>>|main|SimpleLogTest|main
Mon 2006/05/01 21:13:31.121|   |main|SimpleLogTest|This is a test of Simple Log.
Mon 2006/05/01 21:13:31.121|---|main|SimpleLogTest|argv|[Testing, debug, of, object, array]
Mon 2006/05/01 21:13:31.131|<<<|main|SimpleLogTest|main

Logging to a file

Up until now, the log output has always been coming out on the console (through System.err, no less). Most people, most of the time, prefer their logging to be written to a log file. With Simple Log, this is as easy as uncommenting a property and setting the value of it to be file name.

So, open up simplelog-config.properties, find the simplelog.logFile property, uncomment it (by deleting the '#' at the start of the line) and write application.log at the end of the line.

Now, if you run the SimpleLogTest class again, you should see no output! However, you should find a file called application.log in the application's working directory that contains the exact same output as it did before. (If you are running from the command line, the working directory should be whichever directory you were in when you ran the Java command. If you are using an IDE, the working directory is usually specified in the runtime configuration for the application.)

If you want your logging to be written to a file as well as to the console, simply uncomment the simplelog.logFile.andConsole property and change its value to true.

That's It

So, you've now started with Simple Log, and I hope it was pretty quick.
There are obviously many more things it can do that aren't covered here, and most of them are adequately explained in the configuration files and the API documentation. There are a few things, though, that can't be adequately communicated in a configuration file or at the top of a class, so you'll probably benefit from reading the rest of the documentation.