Configuring the Log4j node in WebSphere Message Broker

This article shows you how to configure the Log4j node in a WebSphere Message Broker message flow. The Log4j node enables you to use different levels of logging, so that at runtime, without modifying the application code., you can enable or disable specific logging nodes in a message flow while others remain unaffected.

Share:

Kiran Batchu (kirabatc@in.ibm.com), WebSphere MQ and WebSphere Message Broker Administrator, IBM

Kiran Batchu is a WebSphere MQ and WebSphere Message Broker administrator with IBM India. He has a Bachelor of Technology degree in Computer Science, and three years of IT experience with IBM messaging products. You can contact Kiran at kirabatc@in.ibm.com.



29 May 2013

Also available in Chinese

Introduction

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
  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
  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
  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

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.

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


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