This section discusses the setup that is required in both versions of TIBCO BusinessWorks to enable monitoring, as well as the steps needed to install, configure, and setup the Solution Package for TIBCO BusinessWorks (versions 5 and 6). 

Required Setup in TIBCO BusinessWorks (Versions 5 and 6)

Some setup is required in TIBCO BusinessWorks Versions 5 and 6 to enable monitoring. For Version 6, there are two options: You can either install the OSGi plugin in every AppSpace you want to monitor, or you can enable the TIBCO Hawk MicroAgent in each AppSpace you want to monitor. Monitoring via the OSGi plugin is recommended for better performance and reliability.

For Version 5, monitoring must be done via TIBCO Hawk, which is enabled by default, but you also need to install the RTViewBWAgent plug-in microagent. If you enable JMX monitoring, you can access additional data such as CPU and Memory data. For BWSE engines, additional setup is needed to allow access to AMX Node data.

Enable Monitoring via OSGi Plugin for Version 6

This section describes the “Prerequisites” and steps required to install the RTView OSGi (Open Service Gateway Initiative) BusinessWorks plugin into “RTView TIBCO BusinessWorks”, “Docker”, and “Cloud Foundry”. 

Configuration

The RTView OSGi plugin is configured with the following properties:

Note that the receiving RTView dataserver must be run using the -propfilter:receiver flag. This is the default for all RTView distributions except for RTViewDataCollector. If you are using that distribution you should add the flag to your start_servers command. For example:

Containers

With the container deployments you may also use the following properties to provide specific names for the domain, appspace, and appnode:

For example: 

If you supply specific names then your containers will appear in the displays as if they were appnodes in an appspace. Furthermore, if multiple containers
are instances of the same application, the metrics of the container appnodes will be summed for the application, as if it were deployed to the appspace. If you don not supply specific names, the following names will be used:

If you do supply specific names, you can include variables from the container environment in the names by bracketing the environment variable name with '%'. For example, PCF containers have environment variables such as CF_INSTANCE_GUID and CF_INSTANCE_INDEX (The former is used for the appnode name if one is not supplied). If you wanted to name your appnodes "instance-1", "instance-2" etc. then you could supply an appnode name such as:

BusinessWorks

Prerequisites

BW 6.3 or later; Hotfix 2 or later
RTVAPM X.X

The plugin is configured using AppSpace properties with the following procedure.

• Stop all AppSpaces to be monitored. Stop the bwagent, if running.

• Copy the plugin jar to $TIBCO_HOME/bw/<version>/system/shared.

• Start the bwagent. Do not start any AppSpaces or AppNodes yet.

• Navigate to the system config folder: $TIBCO_HOME/bw/<version>/config/

• Copy the appspace_config.ini_template file to a temporary file.

• Edit the temporary file and set the properties as needed.

• Use the bwadmin config command to push the configuration to the AppSpace:

                bwadmin config -d <domain> -cf <temporary-file> appspace <appspace>

• (Optional) For any AppNode, to see plugin output (INFO or TRACE) in the bwappnode.log file, add the following to the User Properties section of the logback.xml file, located at:

               Note: When debugging the behavior of the plugin, it is recommended to set level value to "TRACE".

• Restart the AppSpace.

• Repeat the previous 4 steps for every AppSpace to be monitored.

Note: When upgrading to a new version of the plugin jar, before restarting an AppSpace, it is advisable to delete the contents of the AppNode config directory for each AppNode in the AppSpace. The AppNode config directories are located at:

BWCE: Docker

Prerequisites

BWCE 2.4.2 or later
RTVAPM X.X

You will build your Docker image using your application with the TIBCO base image and including the plugin jar. For example, below we use tibco.bwce.sample.BookStore as the application:

• Download bwce-runtime-<version>.zip from TIBCO and copy it into your BWCE installation at the following location:

• Build the image as such:

• Add the RTView OSGi plugin to your application by copying the application archive and the plugin jar (com.sl.rtvapm.osgi_<version>.jar) to your project directory.

• Create a Docker file containing:

• Build the application:

• Set the plugin properties described above using Java system properties, BW_JAVA_OPTS, and the Docker run command. For example:

• The plugin logs to the console at levels INFO and TRACE. You can set the log level for all packages with BW_LOGLEVEL. For example:

BWCE: Cloud Foundry

Prerequisites

BWCE 2.4.2 or later
RTVAPM X.X

• Download the bwce-buildpack_cf-<version>.zip file from TIBCO.

• Insert the plugin jar into the zip file at /resources/addons/jars. To insert plugin jar in the buildpack zip, proceed as follows on a unix system:

• Upload the buildpack to your cloud. For example:

• Set the plugin properties described above using Java system properties and BW_JAVA_OPTS in the manifest.yml file. For example:

• Push the application. For example:

Enable Monitoring via TIBCO Hawk for Versions 5 and 6

This section discusses the steps required to enable monitoring via TIBCO Hawk for TIBCO BusinessWorks (Versions 5 and 6).

ActiveMatrix BusinessWorks Version 6

Perform these instructions if you are monitoring BusinessWorks version 6:

• Enable your applications for statistics collection. You can do this using the TIBCO BusinessWorks administrator CLI with commands such as:

Repeat for each application you wish to monitor.

• Enable the Hawk MicroAgent in your AppNodes for each AppSpace you wish to monitor. Refer to the Enabling TIBCO Hawk MicroAgent section of the TIBCO BusinessWorks6 Administration Guide.

BusinessWorks Version 5

This section is for BusinessWorks Version 5 users.

Install the RTViewBWAgent plug-in microagent in the Hawk Agent for each domain you have configured to communicate with the Monitor.

RTViewBWAgent detects deployed engines and gets their maximum heap size metrics when the Hawk agent is started. If RTViewBWAgent is not installed, deployed engines are not detected until they have been started and report data to the Monitor. When live data is received the engine is added and its Status is set to LIMITED. The Status remains LIMITEDbecause, although live data metrics are available, the deployment and maximum heap size metrics are still unavailable.

You can also configure the agent to detect deployed engines and make data updates at more frequent, specified intervals. To specify the update interval you uncomment the -update argument in the BWAgentPlugin.hma file and specify a non-zero value. When the -update argument is not used (is commented out), the Monitor does not report that an engine has been deployed or undeployed until the Hawk agent is restarted.

• Navigate to the agents/BWAgentPlugin directory of your Monitor installation and locate the following two files:

• For a given domain, find the plug-in directory via this path:

• Repeat the second step for each Hawk domain you have configured to communicate with the Monitor.

• To (optionally) set RTViewBWAgent to make data updates at more frequent, specified intervals, open the BWAgentPlugin.hma file, uncomment the -update argument and specify a non-zero value. The value, which defaults to 300, represents the update interval in seconds. For example, a value of 3600 updates every hour:

• Copy the BWAgentPlugin.jar file and BWAgentPlugin.hma file into the plug-in directory and restart the Hawk Agent.

Enable Monitoring via JMX for Version 5

BusinessWorks version 5 engines can also be enabled for JMX monitoring as documented in TIBCO BusinessWorks™ Administration, Monitoring the BusinessWorks Engine Using JMX.

Enable monitoring of BW5 engines via JMX

• To enable local JMX monitoring, add the following properties to bwengine.tra:

• After the BW Engine is enabled for JMX monitoring and restarted, it can be monitored by adding a JMX Connection property in the RTView Configuration Application where the Connection Name is the Engine name. See Configuring Data Collection for RTView Manager for more information.

Enable Monitoring of BWSE Engines for Version 5

This section is for TIBCO ActiveMatrix (AMX) users, and describes how to configure BW Monitor to monitor BWSE engines. BW Monitor needs access to AMX Node data stored in EMS message queues on the AMX Host system. To make this data available to BW Monitor you will create EMS topics with bridges from the queues.

The TIBCO BusinessWorks Service Engine (BWSE) is an ActiveMatrix (AMX) component that enables BW engines to participate in the implementation of AMX services. In this case, the BWSE engines run within an AMX Node and are not visible to BW Monitor. However, you can configure BW Monitor to display these engines, as well as to gather JVM memory metrics for the AMX Nodes in which they are running.

Configure for BWSE engines

• To configure the AMX Host, execute the following commands in the EMS administration tool (tibemsadmin):

• In AMX Administrator, in the properties for each BWSE engine, set HawkEnabled to true.

Configuring Data Collection for Hawk (Version 5 or 6)

Note: Only the Classpath and Connections regions on the CONNECTIONS tab need to be set up for TIBCO BusinessWorks (Version 5 or 6). Modifying the configurations on the DATA COLLECTION and DATA STORAGE tabs is optional.

• Navigate to the Solution Package Configuration > TIBCO Hawk > CONNECTIONS tab.

Open

• In the CONNECTIONS tab, specify the classpaths for the TIBCO Hawk jar files, the TIBCO Rendezvous jar files, and the TIBCO EMS jar files.

• Click the 

   icon.

• For TIBCO Hawk domains running on EMS transports, specify the connection information and click SAVE where:

Open

• For TIBCO Hawk domains running on Rendezvous transports, specify the connection information and click SAVE where:

Open

• After you complete these configuration steps and start the RTView Data Server, you can verify your Hawk configuration by viewing the dataserver.log file, located in the logs directory. For example:

Configuring Data Collection for RTView Manager

The configurations defined in this section are only relevant for Version 5 users, and only if they enabled JMX. Version 6 users do not need to complete this section. JMX data is available in the Monitor in the RTView Servers view.

• Navigate to the Solution Package Configuration > RTView Manager > CONNECTIONS tab.

Open

• Click the 

   icon.

Open

• Add a connection for each BusinessWorks engine for which you enabled monitoring via JMX. See “Enable Monitoring via JMX for Version 5” for more information.

• Optionally, navigate to Solution Package Configuration > RTView Manager > DATA COLLECTION > Poll Rates to update the default polling rates for all RTView Manager caches.

Open

Configuring Historical Data for RTView Manager (Optional)

You can specify the number of history rows to store in memory, the compaction rules, the duration before metrics are expired and deleted, and the different types of metrics that you want the Historian to store in the Data Storage tab in the RTView Configuration Application. These configurations already contain default values and modifications to these configurations are optional.

Defining the Storage of In Memory RTView Manager History

You can modify the maximum number of history rows to store in memory in the DATA STORAGE tab. The History Rows property defines the maximum number of rows to store for the JvmGcInfo, JvmMemoryPool, RtvDataServerManager, RtvDisplayServerManager, RtvDataServerClientTotals, TomcatGlobalRequestStats, and TomcatWebModuleTotals caches. The History Rows Large property defines the maximum number of rows to store for the JvmOperatingSystem, JvmThreading, JvmMemory, RtvDataServerClientStats, and TomcatWebModuleStats caches. The default setting for History Rows is 50,000 and the default setting for History Rows Large is 100,000. To update the default settings:

• Navigate to the Solution Package Configuration > RTView Manager > DATA STORAGE tab.

• In the Size region, click the History Rows and History Rows Large fields and specify the desired number of rows.

Open

Defining Compaction Rules for RTView Manager

Data compaction, essentially, is taking large quantities of data and condensing it using a defined rule so that you store a reasonably sized sample of data instead of all of your data, thus preventing you from potentially overloading your database. The available fields are:

• Navigate to the Solution Package Configuration > RTView Manager > DATA STORAGE tab.

• In the Compaction region, click the Condense Interval, Condense Raw Time, and Compaction Rules fields and specify the desired settings.

Open

Defining Expiration and Deletion Duration for RTView Manager Metrics

The data for each metric is stored in a specific cache and, when the data is not updated in a certain period of time, that data will either be marked as expired or, if it has been an extended period of time, it will be deleted from the cache altogether.

The Expire Time field, which sets the expire time for the JvmConnections, JvmGcInfo, JvmMemoryPool, JvmClassLoading, JvmCompilation, JvmOperatingSystem, JvmThreading, JvmMemory, JvmMemoryManager, JvmSystemProperties, RtvDataServerManager, RtvDisplayServerManager, RtvHistorianManager, RtvDataServerClientStats, RtvDataServerClientTotals, RtvServerVersion, TomcatWebModuleStats, TomcatConnectorInfo, TomcatGlobalRequestStats, TomcatHostInfo, and TomcatWebModuleTotals caches, defaults to 45 seconds.

The Delete Time field, which sets the delete time for the JvmConnections, JvmGcInfo, JvmMemoryPool, JvmClassLoading, JvmCompilation, JvmOperatingSystem, JvmRuntime, JvmThreading, JvmMemory, JvmMemoryManager, JvmSystemProperties, RtvDataServerManager, RtvDisplayServerManager, TomcatWebModuleStats, TomcatGlobalRequestStats, TomcatWebModuleTotals, RtvHistorianManager, RtvDataServerClientStats, RtvDataServerClientTotals, RtvServerVersion, TomcatWebModuleStats, TomcatConnectorInfo, TomcatGlobalRequestStats, TomcatHostInfo, and TomcatWebModuleTotals caches, defaults to 3600 seconds. To modify these defaults:

• Navigate to the Solution Package Configuration > RTView Manager > DATA STORAGE tab.

• In the Duration region, click the Expire Time and Delete Time fields and specify the desired settings.