Basic concepts

In order to understand Splitlog, you should first learn about the basic building blocks of the tool. Worry not, it’s only a short list.

• First and foremost, we have the LogWatch. This is the piece of code that periodically checks a log file for changes. For every log file that you want to use within Splitlog, you need one LogWatch and you will get it through LogWatchBuilder. When you have LogWatch tracking changes in a log file, we call that watching the log and the file is called watched file.

• Watched files will be read line by line and these lines will be put together into a Message. A Message would typically look like this:

  15:11:42,044 WARN [org.mylogger] (thread-1) This is a warning.

  Alternately, Message can also span multiple lines, like this one containing an exception stack trace:

  15:11:49,051 ERROR [org.mylogger] (thread-1) Some exception

  at org.switchyard.internal.ServiceReferenceImpl.createExchange(ServiceReferenceImpl.java:118) [switchyard-runtime-1.1.1.jar:1.1.1]

  You will not be notified of each line – but you will be notified every time another line is added to a Message, be it a new Message or a continuation of the previous one. The beginning and the end of each Message is determined by the Splitter, but more on that later.

• Message consumer is a piece of code that is notified whenever a new line appears in the log, resulting in a Message. There are various kinds of consumers, most important of which is the Follower, as explained below.
• Your consumers will only be notified of Messages if you are following the watched file. Following can be started from the LogWatch, at which point you will be given a Follower instance. Follower is your window into the watched log file – it will contain only the Messages that have arrived since you started following the LogWatch, until you either stop following or you stop watching.

And that’s it, folks! You can now start using Splitlog. Let’s see how.

Simple example

Before we start, let’s make sure you have Splitlog on your Java classpath. Either include the uber jar or, preferably, use Maven:

<dependency>
  <groupId>com.github.triceo.splitlog</groupId>
  <artifactId>splitlog-core</artifactId>
  <version>1.6.0-RC3</version>
</dependency>

Now that this is behind us, let us look at the simplest possible Splitlog use case:

  File myLogFile = new File("server.log");
  LogWatchBuilder builder = LogWatchBuilder.getDefault().watchingFile(myLogFile);
  LogWatch watch = builder.build();
  Follower follower = watch.startFollowing();
  // [snip] insert whatever code here [/snip]
  System.out.println(follower.getMessages());

You know what? Let’s take it line by line. Here, you tell Splitlog to prepare a LogWatch that would watch the file stored in the myLogFile variable:

  LogWatchBuilder builder = LogWatchBuilder.getDefault().watchingFile(myLogFile);

Here, you actually retrieve this LogWatch:

  LogWatch watch = builder.build();

And, to top it all off, you start following the file to start receiving notifications on new Messages. Based on the configuration of the LogWatch, it is possible that the LogWatch will only actually start watching the log now:

  Follower follower = watch.startFollowing();

Now would be a good time to let Splitlog wait for some Messages to be read from the log. Here goes some code that your application actually needs to do while the logs are being filled with stuff. And, when it’s over, you can print every Message received in the meantime:

  System.out.println(follower.getMessages());

What remains is to clean up.

  follower.stop();
  watch.terminate(); // this one will suffice

And that’s it. You’re done. But Splitlog offers much more?