Take a peek inside

When a TIBCO BusinessWorks engine is started, nJAMS Client for BW gets initialized as well. At the beginning nJAMS Client for BW determines all process definitions within the BW engine and creates a project message containing the process definitions. Based on the process definitions, nJAMS is able to show the process graph as the developer has designed in TIBCO Designer.

As soon as a TIBCO BusinessWorks process is executed, nJAMS Client for BW starts monitoring the process execution. nJAMS Client for BW sends event messages containing collected information about the process execution to the nJAMS Instance. nJAMS event messages contain information for example about process start / end, duration, status, and execution path of the process.

One main objective of nJAMS Client for BW is to collect monitoring information with as little interference on the BW engine as possible. Nevertheless, collecting process information as well as creating and sending event messages may take time and may consume resources depending on the load of the BW engine. nJAMS Client for BW has advanced features to save resources of the BW engine. Even if the BW engine is under high load, nJAMS Client for BW is able to gently deal with it.

nJAMS Client for BW comes with proper default settings for the most scenarios. But there are also several properties of nJAMS Client for BW that can be individually adjusted to deal with high load scenarios. Some of the most important settings are introduced here.

General configuration aspects:

In general, nJAMS Client for BW can be configured either by using configuration file, or on the fly by using nJAMS UI. The configuration itself is divided into two parts. The first part covers the basic operation of nJAMS Client for BW in context of the entire BW engine. The second part is related to the way how nJAMS Client for BW monitors individual processes within the BW engine.

Configuration file

nJAMS Client for BW uses BW engine’s TRA file for the general configuration of nJAMS Client for BW, the communication (Data Providers), and the memory management. To configure nJAMS Client for BW just add nJAMS Client for BW properties to each BW engine’s TRA file or modify bwengine.tra file, the TIBCO BusinessWorks configuration template file. The basic properties, used to send/receive messages to/from the nJAMS Instance, can also be configured by Global Variables. Changing nJAMS Client for BW properties via BW engine’s TRA file requires a restart of the BW engine(s). Changing nJAMS Client for BW’s Global Variables requires a redeployment and a restart of the BW engine’s. The specific configuration of nJAMS Client for BW related to individual processes within the BW engine, takes place in a separate configuration file. This file is located in the resource folder of the deployed BW engine. It contains settings for log level, process exclusion, Extracts, Tracing, etc. Please refer to nJAMS Server User Guide for more information about monitoring processes.

nJAMS UI

Another way to change nJAMS Client for BW’s configuration is to use nJAMS UI. Configuration changes via nJAMS UI take effect immediately and do not require a restart of the BW engine(s). Changes you make via nJAMS UI are provided to nJAMS Client by sending command messages. nJAMS Client for BW receives the commands and stores the configuration in the nJAMS Client configuration file. The settings related to BW engine’s TRA file are not updated by nJAMS UI.

Important configuration properties:

Max Queue Length

nJAMS Client for BW has an internal queue that temporarily collects events from the BW engine. In case the BW engine starts more jobs than nJAMS Client for BW can process, the events are buffered in that internal queue.

The default value for the maximum queue length is 20:

tibco.clientVar.nJAMS/MemoryManagement/maxQueueLength=20:

When maxQueuelength exceeds, nJAMS Client for BW will by default slow down the BW engine until the internal buffer can take up events again. If you permanently encounter a higher load of the BW engine, you can increase the internal queue by configuring this property. Please keep in mind, the higher the internal queue, the more heap is required and you may be required to increase MaxHeap setting of the BW engine.

Max Message Size

Since nJAMS Client for BW collects monitoring events for a certain time and wraps multiple events into one event message, the event message may grow to a considerable size. Especially if you want nJAMS Client for BW to monitor the entire payload of a process execution or the monitored process consists of many iterations, the event message may become large. To prevent the event message from becoming arbitrarily large the maximum message size can be limited.

By default the limit is 10 MB:

tibco.clientVar.nJAMS/MemoryManagement/maxMessageSize=10:

In case the maximum message size is reached, the event message is being sent and the allocated heap is released.

Another option to prevent large event messages is to reduce the period of time that is used to collect events.

By default the timeout push interval is 30 seconds:

tibco.clientVar.nJAMS/DataProvider/timeoutPush=30000:

After 30 seconds the event message is pushed out.

Discard Policy

In high load scenarios it may happen that maxQueueLength is temporarily exceeded. In that case nJAMS Client for BW has to decide how to proceed.

By default, nJAMS Client for BW slows down the BW engine in order to get time to process event messages:

tibco.clientVar.nJAMS/MemoryManagement/discardPolicy=none:

This setting gurantees that no event message is lost even in high load scenarios. Of course the trade off is that the performance of the BW engine might be slightly reduced.

In case you do not want the BW engine from being slowed down, you can configure discard policy to discard event messages:

tibco.clientVar.nJAMS/MemoryManagement/discardPolicy=discard:

This setting forces nJAMS Client for BW to discard event messages, when maxQueueLength is exceeded. This is the recommended setting, if you want to run the BW engine without impact and want to loose event messages in case of emergency.

There is also a combination available of temporarily slowing down the BW engine and discarding event messages. Assume your JMS provider is not available and nJAMS Client for BW could not deliver event messages. In this scenario nJAMS Client for BW would block the BW engine until the JMS provider is available again. Since not only the active processes are pending, but also the BW engine starts more and more processes, more and more memory is required by the BW engine and the situation is getting even worse the longer the JMS Server needs to get recovered. At some point the BW engine will be out of heap.

In order to prevent this emergency, the discard policy can be set to onConnectionLoss:

tibco.clientVar.nJAMS/MemoryManagement/discardPolicy=onConnectionLoss:

This setting forces nJAMS Client for BW to discard event messages, only if the connection to the JMS provider is lost. In all other cases, the BW engine will be temporarily slowed down.

If the BW engine is permanently under high pressure, you should consider to increase MaxQueueLegth to a reasonable value.

Instant Push

nJAMS Client for BW allows to control whether to collect events within a period of time and send the collected events by one single message or to send individual event messages for each event.

By default, nJAMS Client for BW collects events for a period of time:

tibco.clientVar.nJAMS/DataProvider/instanPush=false:

You can set instantPush to true, if you want to prevent nJAMS Client for BW from collecting events. This might be useful, if you want to see log events in nJAMS UI as promptly as possible, or you want to avoid issues with maxQueueLength as described before. But keep in mind the overall effort in nJAMS Client for BW and in nJAMS Server is much bigger, if instantPush is on. nJAMS Client for BW has to create and send event messages on each single event, which causes a higher consumption of cpu and heap resources. Furthermore, nJAMS Server has to process much more incoming event messages, which is also more expensive. Overall it is recommended to leave instanPush to off.

logMode

This is the fundamental property to enable, respectively disable nJAMS Client for BW.

The default setting for logMode is complete:

tibco.clientVar.nJAMS/logMode=complete:

nJAMS Client for BW is enabled.

In exceptional situations you might want to turn off nJAMS Client for BW entirely in your BW engine. In this specific case set logMode to none:

tibco.clientVar.nJAMS/logMode=none:

nJAMS Client for BW is entirely disabled and does allocate almost no resources. Only the command interface is still active in order to receive commands from nJAMS UI. This is required to be able to turn on nJAMS Client for BW again. In addition, nJAMS Client for BW is still able to calculate Log IDs, which is required, when you use nJAMS log activities in your process design.

Subagent

The nJAMS Subagent is a built-in component, which is used to monitor various metrics in connection with nJAMS Argos.

By default, nJAMS Subagent is enabled and communicates with nJAMS Agent on the same machine:

# Enable nJAMS Subagent:
tibco.clientVar.nJAMS/Subagent/enabled=true
tibco.clientVar.nJAMS/Subagent/host=localhost
tibco.clientVar.nJAMS/Subagent/prot=6450

If you are not using nJAMS Argos, you can turn off nJAMS Subagent and save resources:

# Disable nJAMS Subagent:
tibco.clientVar.nJAMS/Subagent/enabled=false

Please refer to nJAMS Agent User Guide for more information about configuring nJAMS Agent and refer to nJAMS Argos User Guide to learn more about nJAMS Argos.