The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
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