System.Log.Handler.Log4jXML

hslogger-1.2.10: Versatile logging framework

Copyright | Copyright (C) 2007-2011 John Goerzen
License | BSD3
Maintainer | bjorn.buckwalter@gmail.com
Stability | experimental
Portability | GHC only?
Safe Haskell | Safe
Language | Haskell98

System.Log.Handler.Log4jXML

Contents

- Introduction
  - Handlers with hslogger levels
  - Handlers with log4j levels
- Java install process
- Chainsaw setup
- Example usage
- References

Description

log4j[1] XMLLayout log handlers.

Written by Bjorn Buckwalter, bjorn.buckwalter@gmail.com

Synopsis

- log4jStreamHandler :: Handle -> Priority -> IO (GenericHandler Handle)
- log4jFileHandler :: FilePath -> Priority -> IO (GenericHandler Handle)
- log4jStreamHandler' :: Handle -> Priority -> IO (GenericHandler Handle)
- log4jFileHandler' :: FilePath -> Priority -> IO (GenericHandler Handle)

# Introduction

This module provides handlers for hslogger that are compatible with log4j's XMLLayout. In particular log messages created by the handlers can be published directly to the GUI-based log viewer Chainsaw v2[2].

The set of log levels in hslogger is richer than the basic set of log4j levels. Two sets of handlers are provided with hslogger4j, one which produces logs with hslogger's levels and one which "demotes" them to the basic log4j levels. If full hslogger levels are used some Java installation (see below) is necessary to make Chainsaw aware of them.

Usage of the handlers in hslogger4j is analoguous to usage of the `StreamHandler` and `FileHandler` in System.Log.Handler.Simple. The following handlers are provided:

## Handlers with hslogger levels

log4jStreamHandler :: Handle -> Priority -> IO (GenericHandler Handle)

Create a stream log handler that uses hslogger priorities.

log4jFileHandler :: FilePath -> Priority -> IO (GenericHandler Handle)

Create a file log handler that uses hslogger priorities.

## Handlers with log4j levels

log4jStreamHandler' :: Handle -> Priority -> IO (GenericHandler Handle)

Create a stream log handler that uses log4j levels (priorities). The priorities of messages are shoehorned into log4j levels as follows:

        DEBUG                  -> DEBUG
        INFO, NOTICE           -> INFO
        WARNING                -> WARN
        ERROR, CRITICAL, ALERT -> ERROR
        EMERGENCY              -> FATAL

This is useful when the log will only be consumed by log4j tools and you don't want to go out of your way transforming the log or configuring the tools.

log4jFileHandler' :: FilePath -> Priority -> IO (GenericHandler Handle)

Create a file log handler that uses log4j levels (see `log4jStreamHandler'` for mappings).

# Java install process

This is only necessary if you want to use the hslogger levels.

Add `hslogger4j.jar` from `contrib/java` to your classpath. To use you will also need to have the jars `log4j-1.3alpha-7.jar` and `log4j-xml-1.3alpha-7.jar` that are distributed with Chainsaw on your classpath.

(On Mac OS X I added all three jars to `~/Library/Java/Extensions`. It seems that it is not sufficient that Chainsaw already includes its jars in the classpath when launching - perhaps the plugin classloader does not inherit Chainsaw's classpath. Adding the jars to `~/.chainsaw/plugins` wouldn't work either.)

If for whatever reason you have to rebuild the hslogger4j jar just run `ant`[3] in the `contrib/java` directory. The new jar will be created in the `contrib/java/dist` directory. The Java source code is copyright The Apache Software Foundation and licensed under the Apache Licence version 2.0.

# Chainsaw setup

If you are only using the basic log4j levels just use Chainsaw's regular facilities to browse logs or listen for log messages (e.g. `XMLSocketReceiver`).

If you want to use the hslogger levels the easiest way to set up Chainsaw is to load the plugins in `hslogger4j-plugins.xml` in `contrib/java` when launching Chainsaw. Two receivers will be defined, one that listens for logmessages and one for reading log files. Edit the properties of those receivers as needed (e.g. `port`, `fileURL`) and restart them. You will also want to modify Chainsaw's formatting preferences to display levels as text instead of icons.

# Example usage

In the IO monad:

    lh2 <- log4jFileHandler "log.xml" DEBUG
    updateGlobalLogger rootLoggerName (addHandler lh2)

    h  <- connectTo "localhost" (PortNumber 4448)
    lh <- log4jStreamHandler h NOTICE
    updateGlobalLogger rootLoggerName (addHandler lh)

# References

1. http://logging.apache.org/log4j/
2. http://logging.apache.org/chainsaw/
3. http://ant.apache.org/