Configuring the Log4j node in WebSphere Message Broker

Comments

About Log4j

In IBM® WebSphere® Message Broker, the Trace node is used for logging, but it has two limitations:

  • It does not have configurable log levels.
  • It is not extensible to other targets.

The well-known open-source Log4j logging framework from Apache Software Foundation solves those two limitations for Java-base applications. The WebSphere Message Broker IAM3 SupportPac provides a node that can be used by message flows in order to address all targets reachable by Log4j and configure log levels at runtime. To change the logging, you do not have to restart the broker or message flow, and the change is effective without delay.

Log4j is written in Java and has been ported to the C, C++, C#, Perl, Python, Ruby, and Eiffel languages. Log4j enables you to control logging behavior by editing a configuration file without touching the application code, so that logging statements can remain in shipped code without harming performance. Another feature of Log4j is inheritance in a logger hierarchy, which reduces the volume of logged output and the performance costs of logging. Log4j lets you direct log output to a file, an OutputStream, a java.io.Writer, a remote Log4j server, and to other output targets.

You can use Log4j to insert logging points into the code to make visible key progress points. For example:

  • When a message is accepted at an Input node of any protocol, insert an INFO log point.
  • After a message is put to an Output node of any protocol, insert an INFO log point.
  • If a message is split into several parts, insert an INFO log point after the node performing the split.
  • If you use a service call mechanism such as an HTTPRequest node or an MQRequest node, insert INFO log points to show that a request was sent and a response was received.
  • If you use resend logic, insert WARNING log points, unless you are using a framework that already contains such logging.

Log4j severity levels

As shown below, four severity levels are defined in the Log4j logging framework and used to identify and tag different events so that you can apply filtering. You need to assign an appropriate log level for each message that is to be logged.

  • ERROR -- Use when an application encounters a problem from which it cannot recover. Failing to process a message can be classified as an ERROR.
  • WARN -- Use to indicate that a non-critical error has occurred. For example, a retransmission loop has been started, or a table has missing data but the integration can recover.
  • INFO -- The "normal" severity level -- use for important events in an integration, such as message received, message committed to a queue, or the result of a routing decision.
  • DEBUG -- Use for logging information for debugging purposes -- usually during development. The DEBUG level is filtered in all environments except in the development environment.

Log4j limitations

  • The field Environment.Variables.Log4j.LogText takes precedence if it has a value when the Log4j node is reached.
  • The XPath and ESQL styles always wrap the result of an expression with the string() function, and no other XPath function is supported. If you want to output additional information, use the XML or XESQL styles.
  • The name of the flow is mapped to the thread property for Log4j using the Log4j node. In ESQL, you must provide this name explicitly, because it is not accessible because of ESQL to Java mappings.

Configuring the Log4j node in WebSphere Message Broker

Installing the Log4j node in WebSphere Message Broker Toolkit

  1. Download the WebSphere Message Broker IAM3 SupportPac: Node for Log4j.
  2. From the downloaded zip file, extract Log4jLoggingPlugin_v1.1 zip into the Plug-in folder, which for the V7 Toolkit is C:\Program Files\IBM\WMBT700\plugins. You can see the extracted folder in Figure1:
    Figure 1. Copy Log4j Logging Plug-in folder in Plug-in folder.
    Copy Log4j Logging Plug-in folder in Plug-in folder
    Copy Log4j Logging Plug-in folder in Plug-in folder
  3. Restart the Toolkit.

Installing the Log4j node in WebSphere Message Broker

  1. To Install the plug-in in the WebSphere Message Broker runtime, copy the three files Log4jLoggingNode_v1.1.1.jar, jakarta-oro-2.0.4.jar, and log4j-1.2.8.jar to the MQSI\Shared Classes folder. The default path is C:\Documents and Settings\All Users\Application Data\IBM\MQSI\shared-classes, but the path depends on your installation setup.
    Figure 2. Copy three files to Shared Classes Folder
    Copy three files to Shared Classes Folder
    Copy three files to Shared Classes Folder
  2. Copy Log4jLoggingNode_v1.1.1 to the folder C:\Program Files\IBM\MQSI\7.0\jplugin, as shown below:
    Figure 3. Log4jLoggingNode_v1.1.1 file in jplugin Folder
     Log4jLoggingNode_v1.1.1 file in jplugin Folder
    Log4jLoggingNode_v1.1.1 file in jplugin Folder
  3. Restart the WebSphere Message Broker runtime.

Using the Log4J node in a message flow

To use the Log4J node, you need to populate an XML file with the location of the log file and the logging levels desired. This XML file is the configuration input for the broker at runtime. By default, the filename is brokerlog.xml, and this file along with brokerlog.dtd must be present in the broker CLASSPATH, as shown below. The Log4J node also requires some initialization before you use it.

Listing 1. ESQL code in Compute node
CREATE FUNCTION initLog4j( IN CONFIG_FILE_NAME CHARACTER )
   RETURNS BOOLEAN
   LANGUAGE JAVA
   EXTERNAL NAME "com.ibm.broker.IAM3.Log4jNode.initLog4j";
   CREATE FUNCTION log4j_1_1( IN COMPONENT_NAME CHARACTER,
   IN LOGGER_NAME CHARACTER,
   IN LEVEL CHARACTER,
   IN TEXT CHARACTER )
   RETURNS BOOLEAN
   LANGUAGE JAVA
   EXTERNAL NAME "com.ibm.broker.IAM3.Log4jNode.log";
CREATE PROCEDURE Initialize_Log4j()
   BEGIN
   DECLARE rc BOOLEAN;
   IF (SIMPOC_Log4j_Initialized.valid = NULL) THEN
   CALL initLog4j('brokerlog.xml') INTO rc;
   IF ( rc = FALSE ) THEN
   THROW USER EXCEPTION MESSAGE 5560 VALUES ('Error Initializing log4j');
   END IF;
   SET SIMPOC_Log4j_Initialized = TRUE;
   CALL log4j_1_1(SQL.MessageFlowLabel, 'default', 'WARN', 'initLog4j() 
         completed initialization of log4J env.' ) INTO rc;
   END IF;
   END;

To call the function, use CALL Initialize_Log4j();. The data to be logged must be present in the environment before control reaches the Log4j node: SET Environment.Variables.Log4j.LogText ="USER DEFINED LOG";.

You can also log the information by writing an Xpath expression to extract data from the incoming message. As shown below, this node will log the data in the Environment.Variables.Log4j.LogText variable:

Figure 4. Message flow MF_LOG4J_1.msgflow
Message flow MF_LOG4J_1.msgflow
Message flow MF_LOG4J_1.msgflow

Conclusion

This article showed you how to configure and implement the Log4j node in WebSphere Message Broker, in order to enable logging at runtime without modifying the application code. The article also explained the pros and cons of using a Log4j node in a message flow. Logging should be implemented in each message flow to show its operation.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=931299
ArticleTitle=Configuring the Log4j node in WebSphere Message Broker
publish-date=05292013