Configuring the Log4j node in WebSphere Message Broker

First we will see why we should use Log4j node to trace business data when we could do the same with a Trace node.

The main difference between Log4j Node and trace node is... While using  trace node we can either switch on or switch off trace, we can’t control it any further, we have no other option but to disable or enable tracing on a message flow.This is not the case with Log4j Node, this node provides us with Levels of logging which can be enabled and disabled at runtime… Which enables us to stop specific logging nodes of a same message flow while others are running.

Installing Log4j is a two step process On the Toolkit and Runtime

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.

Installing on toolkit:

From the Downloaded zip file we must first extract the Log4jLoggingPlugin_v1.1 zip to the Plugins folder which is

C:\Program Files\IBM\WMBT700\plugins(default for V7 toolkit) you can see the extracted folder in the red square. After doing this we will have to restart the toolkit for this to take effect.

Broker Installation:

        To Install this plugin in the runtime we will have to copy the below listed files to …MQSI\Shared Classes Folder the default path is “C:\Documents and Settings\All Users\Application Data\IBM\MQSI\shared-classes” but it depends on your installation setup…

Below is the list of files to be copied.

• Log4jLoggingNode_v1.1.1.jar
• jakarta-oro-2.0.4.jar
• log4j-1.2.8.jar
  
  
  
  You can see the files in the red box.

The next step is to copy the “Log4jLoggingNode_v1.1.1” to the “C:\Program Files\IBM\MQSI\7.0\jplugin” Folder

Restart the broker runtime to take effect.

Using The Log4J Node in Flow: 

Using this node requires us to configure a XML file, which holds the information regarding Location of log file and the Level of Log that has to be logged. This Xml is the Configuration input which we give to the broker at runtime, by default the file name is “brokerlog.xml” this file along with the “brokerlog.dtd” must be present in the broker CLASSPATH as shown below.

CODING THE Log4J Node

The Log4J node requires some initialization before it is run, let’s see how to initialize the Environment for this node to run.

On the ESQL side…

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;

And to call the function we will have to 
CALL Initialize_Log4j();

The data to be logged should be present in the Environment before control reaches Log4j node

SET Environment.Variables.Log4j.LogText = “USER DEFINED LOG”;

Or We can log the info by writing an xpath expression …(which would extract data from incoming message)

As shown in the diagram this node will log the data present in Environment.Variables.Log4j.LogText variable.

 

For More information on this check out this link:-

http://www-01.ibm.com/support/docview.wss?uid=swg24021221