/ 
Log-Log4perl-Layout-XMLLayout-0.03
River stage zero No dependents
/ Log::Log4perl::Layout::XMLLayout

NAME

Log::Log4perl::Layout::XMLLayout - XML Layout

SYNOPSIS

use Log::Log4perl::Layout::XMLLayout;

my $app = Log::Log4perl::Appender->new("Log::Log4perl::Appender::File");

my $logger = Log::Log4perl->get_logger("abc.def.ghi");
$logger->add_appender($app);

# Log with LocationInfo
my $layout = Log::Log4perl::Layout::XMLLayout->new(
  { LocationInfo => { value => 'TRUE' },
    Encoding     => { value => 'iso8859-1'}});
    
$app->layout($layout);
$logger->debug("That's the message");

########################### Log4perl Config File entries for XMLLayout
log4perl.appender.A1.layout			= Log::Log4perl::Layout::XMLLayout
log4perl.appender.A1.layout.LocationInfo	= TRUE
log4perl.appender.A1.layout.Encoding		=iso8859-1
###########################

DESCRIPTION

Creates a XML layout according to http://jakarta.apache.org/log4j/docs/api/org/apache/log4j/xml/XMLLayout.html

Logfiles generated based on XMLLayout can be viewed and filtered within the log4j chainsaw graphical user interface (see example section below). chainsaw is part of the JAVA based log4j package and can be downloaded from http://jakarta.apache.org/

The output of the XMLLayout consists of a series of log4j:event elements as defined in the log4j.dtd. It does not output a complete well-formed XML file. The output is designed to be included as an external entity in a separate file to form a correct XML file.

For example, if abc is the name of the file where the XMLLayout ouput goes, then a well-formed XML file would be:

<?xml version="1.0" ?>

<!DOCTYPE log4j:eventSet SYSTEM "log4j.dtd" [<!ENTITY data SYSTEM "abc">]>

<log4j:eventSet version="1.2" xmlns:log4j="http://jakarta.apache.org/log4j/"> &data; </log4j:eventSet>

This approach enforces the independence of the XMLLayout and the appender where it is embedded.

The version attribute helps components to correctly intrepret output generated by XMLLayout. The value of this attribute should be "1.1" for output generated by log4j versions prior to log4j 1.2 (final release) and "1.2" for relase 1.2 and later.

Methods

new()

The new() method creates a XMLLayout object, specifying its log contents. NDC is explained in "Nested Diagnostic Context (NDC)" in Log::Log4perl.

Attributes

LocationInfo

If LocationInfo is set to TRUE, source code location info is added to each logging event.

Encoding

adds XML version and character encoding attributes to the log. Following line is generated only when the first logger call is done:

<?xml version = "1.0" encoding = "iso8859-1"?>

This line will not be generated if the Encoding attribute is undefined. This is required when using chainsaw to view XMLLayouted logfiles.

Example

To view an filter XMLLayouted files in Chainsaw, create a chainsaw configuration file like

<log4j:configuration debug="true">

  <plugin name="XMLSocketReceiver" class="org.apache.log4j.net.XMLSocketReceiver">
          
    <param name="decoder" value="org.apache.log4j.xml.XMLDecoder"/> 
    
    <param name="Port" value="4445"/> 
    
  </plugin>
  
  <root> <level value="debug"/> </root> 
  
</log4j:configuration>

and name it e.g. config.xml. Then start Chainsaw like

java -Dlog4j.debug=true -Dlog4j.configuration=config.xml \

  -classpath ".:log4j-1.3alpha.jar:log4j-chainsaw-1.3alpha.jar" \
  
  org.apache.log4j.chainsaw.LogUIand watch the GUI coming up.

Configure Log::Log4perl to use a socket appender with an XMLLayout, pointing to the host/port where Chainsaw (as configured above) is waiting with its XMLSocketReceiver:

use Log::Log4perl qw(get_logger);

use Log::Log4perl::Layout::XMLLayout;  my $conf = q(

  log4perl.category.Bar.Twix          = WARN, Appender
  
  log4perl.appender.Appender          = Log::Log4perl::Appender::socket
  
  log4perl.appender.Appender.PeerAddr = localhost
  
  log4perl.appender.Appender.PeerPort = 4445
  
  log4perl.appender.Appender.layout   = Log::Log4perl::Layout::XMLLayout
  
);  

Log::Log4perl::init(\$conf);

XML Document Type Definition

<!ELEMENT log4j:eventSet (log4j:event*)>

<!ATTLIST log4j:eventSet

includesLocationInfo   (true|false) "true"

>

<!ELEMENT log4j:event (log4j:message, log4j:NDC?, log4j:throwable?, log4j:locationInfo?) >

<!-- The timestamp format is application dependent. -->

<!ATTLIST log4j:event logger CDATA #REQUIRED priority CDATA #REQUIRED thread CDATA #REQUIRED timestamp CDATA #REQUIRED >

<!ELEMENT log4j:message (#PCDATA)>

<!ELEMENT log4j:NDC (#PCDATA)>

<!ELEMENT log4j:throwable (#PCDATA)>

<!ELEMENT log4j:locationInfo EMPTY>

<!ATTLIST log4j:locationInfo

class  CDATA	#REQUIRED

method CDATA	#REQUIRED

file   CDATA	#REQUIRED

line   CDATA	#REQUIRED

>

INSTALLATION

To install this module type the following:

perl Makefile.PL

make

make test

make install

KNOWN BUGS

Some older versions of chainsaw use a different DTD. Consequently, these versions do not display log events generated via XMLLayout.

AUTHOR

Guido Carls <gcarls@cpan.org>

COPYRIGHT AND LICENCE

Copyright (C) 2003 G. Carls

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

SEE ALSO

Log::Log4perl