CandleMonitor Node

The CandleMonitor node icon

The CandleMonitor node is part of the IBM Tivoli OMEGAMON XE for Messaging: WebSphere Message Broker Monitoring product. It collects statistics on message flow performance and optionally produces event messages for OMEGAMON XE detection. It is a simple pass-through node with one input terminal ("in") and one output terminal ("out"). A CandleMonitor node propagates a message without change from the input terminal to the output terminal.

Positioning CandleMonitor Node to Monitor Statistics

The primary use of the CandleMonitor node is to produce statistics. It is important that the node be placed properly in message flows so that the monitoring product statistics reports contain useful data. For the best statistics, when designing a message flow, a CandleMonitor node should be placed just after the MQInput node. The "type" attribute of a node placed in this position should be changed to "input". If you want to place only one CandleMonitor node in a message flow, the "input" position is the best choice, since most statistics are generated from this position. However, another key position for placing the node is just before any output node such as the MQOutput, MQReply or Publication node to allow for output rate calculation. Here the "type" attribute of the node should be changed to "output".

Monitoring sub-flows

Statistics can optionally be produced for parts of message flows, referred to here as sub-flows. A sub-flow may be a separate message flow embedded in a main message flow (Type I), or just a group of one or more nodes in a flow defined as a sub-flow using the CandleMonitor node (Type II).

To monitor a Type I sub-flow, a CandleMonitor node should be placed just after the Input Terminal in the flow and another CandleMonitor node just before the Output Terminal or other output of the flow. All of these nodes should be assigned the same value for the "subFlowName" attribute. The type of the node at the input location should be "subFlowInput". The type of node at the output location should be "subFlowOutput", or "output" if the output is actually a node such as MQOutput and it represents the end of the message flow for a message going down that particular path.

To monitor a Type II sub-flow, a CandleMonitor node should be placed at the start of the desired sub-flow, its type set to "subFlowInput", and the "subFlowName" attribute assigned. Then a CandleMonitor node should be placed at the end of the sub-flow, its type to set to "subFlowOutput", and the same subFlowName attribute value assigned as for the input node. If the section of message flow that is to be monitored has multiple input connectors or multiple output connectors, multiple CandleMonitor nodes need to be added in the same way with the same "subFlowName".

Both the input and output of the flow must be marked with CandleMonitor nodes in order for valid statistics to be calculated. The "subFlowOutput" type CandleMonitor node is required in the sub-flow. It is not optional as is currently the case with the "output" type node for a main message flow. If the "subFlowName" attribute is set along with a "type" attribute of "input", the node will be assumed to be a combination of type "input" and type "subFlowInput" in behavior. If the "subFlowName" attribute is set with a "type" attribute of "output", the node will be assumed to be a combination of type "output" and type "subFlowOutput" in behavior.

Monitoring single points in a message flow

It is possible to place the CandleMonitor node anywhere else in a message flow if you want to gather statistics at a single point in the message flow only and view them in CandleMonitor Node Statistics report views. When placed in this way, the "type" attribute of the node should be "other". For a "type" attribute "other" node, the "subFlowName" attribute can be set, but it simply acts to identify the node as part of the sub-flow and does not affect generated sub-flow statistics.

Generating message flow events

A secondary use of the CandleMonitor node is to produce user-defined message flow events that can be detected via OMEGAMON XE Message Flow Events situations and reports. When a node is placed for this purpose, the "type" attribute should be "other" and the "eventMessage" attribute should be set to the message text that you wish to appear reports and/or detect with situations whenever this node is entered. The CandleMonitor node also captures other information in the event to help identify the part of the message flow affected and the message that is being processed at the time of the event.

Placement of a node for the purpose of generating message flow events is totally up to user discretion, but IBM recommends that nodes not be placed for this purpose in parts of the message flow that are considered normal processing. It is recommended that this feature be utilized in paths of a message flow that process failures or other conditions which are not considered normal and which deserve to be an alert situation. For example, a node may be placed for this purpose after the "failure" terminal on the MQInput node. It is not recommended that the "eventMessage" attribute be set for any "input" or "output" type node. Likewise, the "eventMessage" attribute should only be set for "subFlowInput" or "subFlowOutput" type nodes that are not part of processing in the normal case (for example, in an error handling sub-flow). Any CandleMonitor node automatically generates events for message flow exceptions detected by the node. Note that the CandleMonitor node does not do any error recovery since it is only a pass-through node. In this capacity, it is solely an alert mechanism.

Monitoring queue times

The "collectQueueTime" attribute applies to "input" type nodes and allows turning off collection of queue time statistics. Queue times are calculated using the put-date-and-time of the message in the queue. If the input queue to a message flow will have messages with put-date-and-times that do not reflect accurately when the message was put into the input queue, then when configuring the CandleMonitor "input" type node, the attribute named "collectQueueTime" should be set to "no" so that queue times will not be collected for these messages. Put-date-and-times are not accurate indicators when origin context is preserved for a message during the put by an application to the input queue to the message flow. This commonly occurs when an application is a message mover that moves messages from one queue to another, or when any application passes or sets origin context for a message. In particular, if the input queue to message flow B is the output queue of message flow A, the broker passes the origin context so that the put date and time for the message in message flow B will not allow accurate calculation of queue time. The "collectQueueTime" attribute to the CandleMonitor node in message flow B should be set to "no".

Activating and deactivating CandleMonitor nodes

The "activateNode" attribute allows specifying the activation level of the CandleMonitor node so that it can be turned off. The default setting is "yes" indicating that the node is active (not turned off). For WebSphere Business Integration version 5.0 and after, the "activateNode" attribute is configurable. This means that it can be set during bar file configuration so that it can have a different setting for different bar files, used for instance to deploy for test and production. In addition, version 5.0 allows promoting the attribute setting so that this attribute will have the same setting for each instance of the CandleMonitor node in a message flow. The set of possible values for the attribute supports specification of some general rules for when the node should be active, such as it should be active for all input and output type nodes, but none other. In general, when configuring a CandleMonitor node in a message flow, leave the setting at the default of "yes" to facilitate node usage during testing. Then when deploying to a production broker, configure the bar file setting for "activateNode" to the desired level and promote the attribute to automatically change the setting of all nodes in the flow to that activation level. For versions prior to 5.0 (and for 5.0 as well if desired), the CandleMonitor node plug-in code accepts specification of a runtime override setting for the "activateNode" attribute, allowing different activation levels for different brokers. See the product User's Guide for more information.

CandleMonitor node terminals

CandleMonitor node properties

(C) IBM Corporation 2006. All Rights Reserved