JSR-047 and Commons Logging support

The Log and Trace Analyzer provides standalone and plug-in support for new and existing users of the following logging utilities:

The details of this support are as follows.

  1. Capability to export log messages to a logging agent
    An extension of the java.util.logging.Handler abstract class under the org.eclipse.hyades.logging.java package allows loggers to be configured to export log messages to a Logging Agent.
    This org.eclipse.hyades.logging.java.LoggingAgentHandler handler checks if a java.util.logging.LogRecord log message that is written to a logger can be logged based on the handler's filter and logging level. If the log message is to be logged, a Logging Agent is created with the same name as the logger that logs the message. The message is formatted using an org.eclipse.hyades.logging.java.XmlFormatter and written to the Logging Agent.
     

  2. Capability to convert log messages to XML
    An extension of the java.util.logging.Formatter abstract class under the org.eclipse.hyades.logging.java package allows org.eclipse.hyades.logging.java.LoggingAgentHandler and other handlers to format java.util.logging.LogRecord log messages to XML. This org.eclipse.hyades.logging.java.XmlFormatter formatter converts the java.util.logging.LogRecord message to XML equivalent to the current org.eclipse.hyades.internal.logging.core.XmlGenerator implementation but excluding the host, process, and agent tags. The generated XML is not formatted and the maximum nesting level is set to 4. When formatting, the object is checked if it implements the org.eclipse.hyades.logging.core. IExternalizableToXml interface. If so, the externalizeCanonicalXmlString() API is called in place of XML serialization by means of introspection for performance reasons.

    The following output illustrates the XML conversion of a log message (the string "Hello World" (SEVERE logging level)):
       <LogRecord logging.util.id="java.util.logging.LogRecord_10468105484720000"
   logging.util.agent_idref="AGENT_CREATE.org.eclipse.hyades.tests.java.JavaLoggingTest.1063298146.542"
   logging.util.MsgLoggerLevel="SEVERE" LoggerName="org.eclipse.hyades.tests.java.JavaLoggingTest"
   ResourceBundleName="null" SequenceNumber="0" SourceClassName="org.eclipse.hyades.tests.java.JavaLoggingTest"
   SourceMethodName="main" Message="Hello World" ThreadID="10"
   Millis="1046810548171">
       <ResourceBundle Instance_Name="ResourceBundle" Value="null"/>
    <Level Instance_Name="Level" logging.util.id="java.util.logging.Level_10468105484720001"
           ResourceBundleName="sun.util.logging.resources.logging" Name="SEVERE"
           LocalizedName="SEVERE"><Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484720002"
           Name="java.util.logging.Level" Type="class" Package="java.util.logging"
           Modifers="public" Superclass="java.lang.Object" />
       </Level>
       <Array Instance_Name="Parameters" Value="null" />
    <Throwable Instance_Name="Thrown" Value="null" />
    <Class Instance_Name="Class" logging.util.id="java.lang.Class_10468105484820000"
       Name="java.util.logging.LogRecord" Type="class" Package="java.util.logging"
       Modifers="public" Superclass="java.lang.Object" />
  </LogRecord>

  3. Capability to bootstrap extension classes to existing Java Logging APIs
    To bootstrap the org.eclipse.hyades.logging.java14 extension classes to the existing Java Logging APIs in JDK 1.4.0 and above, add the following entries to the JRE_HOME\lib\logging.properties configuration file before VM start-up or before the java.util.logging.LogManager.readConfiguration() API is called:
    handlers= <your current handlers>, org.eclipse.hyades.logging.java.LoggingAgentHandler
org.eclipse.hyades.logging.java.LoggingAgentHandler.formatter = org.eclipse.hyades.logging.java.XmlFormatter
    
 

    Alternatively, you can use the org.eclipse.hyades.logging.java14
   plug-in extension classes with the existing Java Logging APIs in JDK 1.4.0
   and above on the Logger (for example, handler) and Handler (for example,
   formatter) programmatically at run-time using the addHandler() and 
   setFormatter() APIs, respectively.
    
 


  4. Capability to include a Common Base Event in a log record
    
   An extension of the java.util.logging.LogRecord class under the 
   org.eclipse.hyades.logging.java package enables you to create a
   customized log record for including an 
   org.eclipse.hyades.logging.events.cbe.CommonBaseEvent in a 
   java.util.logging.LogRecord.
    
  
    
   This org.eclipse.hyades.logging.java.CommonBaseEventLogRecord simple
   extends java.util.logging.LogRecord and contains a single reference to
   an org.eclipse.hyades.logging.events.cbe.CommonBaseEvent. You are
   responsible for creating a new 
   org.eclipse.hyades.logging.java.CommonBaseEventLogRecord object before
   writing to the java.util.logging.Logger.
    
 


  5. Capability to allow filtering of logged records from being processed
   by the handler class
    
   You can filter the logged records from being processed by the 
   org.eclipse.hyades.logging.java.LoggingAgentHandler class by setting an
   implementation of the java.util.logging.Filter interface such as the
   org.eclipse.hyades.logging.java.CommonBaseEventFilter (only permits 
   org.eclipse.hyades.logging.java.CommonBaseEventLogRecord to be
   successfully logged) and logging java.util.logging.Level on the
   handler. These values can be set programmatically at run time using the 
   setFilter() and setLevel() APIs, respectively.
    
  
    
   Alternatively, you can add the following entries to the JRE_HOME\lib\logging.properties
   configuration file before VM start-up or before the 
   java.util.logging.LogManager.readConfiguration() API is called:
   
    org.eclipse.hyades.logging.java.LoggingAgentHandler.level = <level>
org.eclipse.hyades.logging.java.LoggingAgentHandler.filter = org.eclipse.hyades.logging.java.CommonBaseEventFilter
    
   
    
   


  6. Capability to create a customized logger for java.lang.Objects
   and  java.lang.Throwables
    
   An implementation of the org.apache.commons.logging.Log
   interface under the org.eclipse.hyades.logging.commons package enables
   you to create a customized logger for logging java.lang.Objects and 
   java.lang.Throwables to a Logging Agent with the same name as the logger.
  
    
   This org.eclipse.hyades.logging.commons.Logger checks if 
   java.lang.Object and/or java.lang.Throwable log messages written
   to a logger can be logged based on the logger's logging level. If the log
   message is to be logged, the java.lang.Object and java.lang.Throwable
   log message is formatted using an 
   org.eclipse.hyades.internal.logging.core.XmlGenerator and written to the
   Logging Agent. When formatting, the object is checked if it implements the 
   org.eclipse.hyades.logging.core. IExternalizableToXml interface. If so,
   the externalizeCanonicalXmlString() API is called in place of XML
   serialization by means of introspection for performance reasons. To bootstrap
   the org.eclipse.hyades.logging.commons.Logger class to the 
   org.apache.commons.logging.LogFactory class,  set the following
   system property on VM start-up:
    
   
    -Dorg.apache.commons.logging.Log=org.eclipse.hyades.logging.commons.Logger
    
   
 

 
 


Precautions 

 

 


    


  1. If you log string log messages,  not imbed XML fragments in the
   message. If you imbed XML fragments in the log message, the XML content will
   be normalized and added to the value of the value attribute of a string tag.
   For example,
    
      <String logging.util.agent_idref="AGENT_CREATE.LoggingUtilSample
   logger.1045075846.538" logging.util.MsgLoggerLevel="FINEST"
   Value="<tag attribute=&quot;value&quot;/>"/>
   
   


  2. If you use the com.ibm.etools.logging.util standalone logging
   utilities,  add the path to the hlcore.jar, hparse.jar, hexl.jar
   and hexr.jar JAR files to the system and VM class path.
 




 



Related concepts

 Common Base Event model