There are currently a number of surprising inconsistencies and omissions in the official site and documentation (where such documentation even exists) about the use of Chainsaw and the network appenders. The following is based on speculation and some experimentation on my part, and is only a best guess:

Background

Chainsaw V2

Chainsaw, as documented and linked from the official log4j page, is Chainsaw V2 - and corresponds, at least in some part, with the as yet unreleased, and (from my own experience) unusable, log4j 1.3. Chainsaw V2 can be downloaded from "this page" for invokation from the shell, and run via webstart from this page.

At this time, the Web Start version of Chainsaw v2 appears to be broken. I am only using the downloadable bundle.

Chainsaw V1.2

An older version of Chainsaw (Chainsaw V1.2) is packaged within the log4j 1.2 releases - within the release jar itself. It can be inoked as follows:

java -classpath log4j-1.2.12.jar org.apache.log4j.chainsaw.Main

if you are within the dist/lib directory of the chainsaw install.

Chainsaw v2 compatiblity with log4j 1.2 appenders

Because log4j's network appenders apparently use serialized objects as the basis for their wire protocol, and because these classes apparently do not use robust, versioned serialization code, and because (though their web pages do not advertise this fact) Chainsaw v2 (the one you'll actually find easily) is based on the newer log4j codebase, compatibility with usable 1.2 appenders is limited.

Because Chainsaw v2 is still quite rough around the edges, you might not even see a descriptive error message when this problem causes it to fail. It just fails quietly and your SocketHubReceiver attempts to reconnect again, and fails again, and so forth.

Apparently, the problems are related to Location information and the MDC. If you are willing to forgo both of these, and you take special precautions when building your log4j configuration, Chainsaw v2 can be made to work with a 1.2 SocketHubAppender.

Specifically, you must define and use your SocketHubAppender "before" any other appenders that may use location information (for instance, in their Patterns). If you fail to do this, you'll get a silent failure in Chainsaw v2.

Chainsaw v1.2 compatibility with SocketHubAppender

Although the earlier version of chainsaw is even more rough around the edges than v2, it may be preferable to some people to use it instead.

I take the liberty of quoting Chris Daniluk's blog here rather than linking to it, since it seems to be down, and this is the only place I was able to find this information:

For being the most ubiquitous Java logger out there, Log4j sure doesn't have its act together. Slow release processes, vague documentation, a new "This is the ONLY way to do it" standard of the week, and an inconsistent shared vision of the project's destiny lead to frustration when you get off the beaten logging path. I went through this today trying to take advantage of Mark Womack's excellent SocketHubAppender which he contributed to Log4j some 2 years ago.

For those of you who don't know what SockerHubAppender does, it creates an effective logging server, letting you connect to it and receive serialized LoggingEvents. This compares to SocketAppender, in which Log4j connects to you and sends data. This has always been dumbfounding to me - and evidently Mark as well, as he contributed what should have been an obvious fix to a stupid problem. Unfortunately, over 2 years later, no one has taken his work and made it useful. The new Chainsaw2 natively supports SocketHubAppender, but the support is a total dud. Despite claims that it works with a Log4j1.2 application, it simply does not. It seems that the last release, 1.99.99, worked after applying a silly workaround, but based on a variety of Googles, it appears 2.0 just flat out does not work with SocketHubAppender to a Log4j 1.2.x deployment.

Thus, we are stuck with an awesome appender and no way to use it. I found repeated references to a patch Mark made to Chainsaw several years ago (that no one merged into the source tree), but had difficulty finding a mailing list archive that held onto attachments. After far too much searching, MARC came through for me. If you'd like to use SocketHubAppender (and you should), check out the chainsaw patch at:

http://marc.theaimsgroup.com/?l=log4j-dev&m=102511373124806&w=2

To run it, something like this will do the trick:

java -classpath ./log4j-chainsaw_mod.jar;log4j-1.2.12.jar org.apache.log4j.chainsaw.Main

Then just click on the Connect menu and enter the host name and port of your SocketHub server.

How-To

  1. Configure your SocketHubAppender. Make sure that the appender is defined, and used, before any other appenders that may use location info (i.e. in a Pattern) In XML:

    • <appender name="sockethub" class="org.apache.log4j.net.SocketHubAppender">

      • <param name="Port" value="4555"/> <param name="LocationInfo" value="false"/>

      </appender>

  2. Start chainsaw.
    1. For Chainsaw v2:
      1. Start from the downloaded archive.
      2. Right-click on Receivers, and add a SocketHubReceiver.

      3. Set the host, name, port, and frequency, in ms. You may wish to define a lower frequency than the default (I use 1000). I have also seen mention (but haven't observed yet) a problem connecting to "localhost" - if you experience this, try using an external hostname instead.
    2. For Chainsaw v1.2
      1. Download Mark Womak's patch from here.

      2. Copy the jar into the dist/lib of your log4j 1.2 install.
      3. Open the shell and cd to that directory.
      4. java -classpath ./log4j-chainsaw_mod.jar;log4j-1.2.12.jar org.apache.log4j.chainsaw.Main

      5. Connect to the desired host. All you do in v1.2 is specify the host and port. You may connect to more than one host at the same time.

Notes

It's possible to write an XML configuration file for at least Chainsaw v2. Chris provided some instructions (which I haven't tried yet):

In the Chainsaw V2 UI, select the View-show application wide preferences menu, and in the 'automatic configuration url' field, enter the URL to this config file, like this:

file:///c:/downloads/log4j/chainsaw-receiver.xml

Here's chainsaw-receiver.xml:

<log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/">

</log4j:configuration>

Thanks

I would never have been able to figure this out if it weren't for the intrepid work of Cris Daniluk and Mark Womak.

ChainsawAndSocketHubWalkthrough (last edited 2011-09-08 07:20:34 by CekiGulcu)