AppDynamics Tibco BW (HAWK) Monitoring Extension

Use Case

TIBCO BusinessWorks™ is a family of next-generation, industry-leading enterprise integration products designed to address the new integration challenges faced when transitioning to a digital business.
The Tibco BW Monitoring Extension executes BW methods using BW hawk microagents and presents them in the AppDynamics Metric Browser.

This extension works only with the standalone machine agent.

Prerequisites

1. Before the extension is installed, the prerequisites mentioned here need to be met. Please do not proceed with the extension installation if the specified prerequisites are not met.

2. Download and install Apache Maven which is configured with Java 8 to build the extension artifact from source. You can check the java version used in maven using command mvn -v or mvn --version. If your maven is using some other java version then please download java 8 for your platform and set JAVA_HOME parameter before starting maven.

Installation

1. Clone the "tibcohawk-monitoring-extension" repo using git clone <repoUrl> command.
2. Create a lib folder in "tibcohawk-monitoring-extension" and copy the following jars in the tibcohawk-monitoring-extension/lib folder. (These jars are shipped with your Tibco product itself)

console.jar, jms.jar, talon.jar, tibjms.jar, tibrvjms.jar, console_agent_shared.jar, security.jar, tibcrypt.jar, tibrvj.jar, util.jar

3. Run 'mvn clean install' from tibcohawk-monitoring-extension
4. Copy and unzip TibcoHawkMonitor-<version>.zip from 'target' directory into <machine_agent_dir>/monitors/
5. Edit config.yml file in TibcoHawkMonitor and provide the required configuration (see Configuration section)
6. Configure BW hawk methods in metrics.xml file in TibcoHawkMonitor
7. Add the following Tibco jars to lib folder. In BW 5.9 all the jars are available in tibrv folder.

console.jar,console_agent_shared.jar,talon.jar,tibrvj.jar,util.jar,jms.jar,security.jar,tibcrypt.jar,tibjms.jar,tibrvjms.jar

8. Set system variables like RV_HOME, PATH and LD_LIBRARY_PATH. For more information take a look at https://docs.tibco.com/pub/api-exchange-gateway/2.2.0/doc/html/GUID-86868063-8A1E-4348-8A5A-8B73772036D8.html
9. Restart the Machine Agent.

Please place the extension in the "monitors" directory of your Machine Agent installation directory. Do not place the extension in the "extensions" directory of your Machine Agent installation directory.

Configuration

config.yml

Note: Please avoid using tab (\t) when editing yaml files. You may want to validate the yaml file using a yaml validator.

metrics.xml

This file contains the methods to execute using BW hawk micro agents and metrics to collect from the method results.

Below is an example config for monitoring multiple BW domains:

#Metric prefix used when SIM is enabled for your machine agent
#metricPrefix: "Custom Metrics|Tibco BW|"

#This will publish metrics to specific tier
#Instructions on how to retrieve the Component ID can be found in the Metric Prefix section of https://community.appdynamics.com/t5/Knowledge-Base/How-do-I-troubleshoot-missing-custom-metrics-or-extensions/ta-p/28695
metricPrefix: "Server|Component:<COMPONENT_ID>|Custom Metrics|Tibco BW"

hawkConnection:
   - displayName: "RV Domain"
     hawkDomain: "testDomain"
     # Supported transport types are tibrv and tibems
     transportType: "tibrv"
     # RV transport properties
     rvService: "7474"
     rvNetwork: ";"
     rvDaemon: "tcp:7474"
     # EMS transport properties
     #emsURL: ""
     #emsUserName:
     #emsPassword:
     bwMicroagentNameMatcher: [".*bwengine.*testDomain.*"]
     #This pattern is matched with the BW microagent name and the name extracted from specified groups(i.e string matched in the parentheses) is used as the display name. If no group found or invalid group used we will use full microagent name.
     #Example, for "COM.TIBCO.ADAPTER.bwengine.testDomain.TestNew.Process Archive" using the below pattern, display name would be "testDomain-TestNew-Process Archive"
     bwMicroagentDisplayNamePattern: "COM.TIBCO.ADAPTER.bwengine\\.(.*)\\.(.*)\\.(.*)"
     bwMicroagentDisplayNameRegexGroups: [1, 2, 3]
     bwMicroagentDisplayNameRegexGroupSeparator: "-"
   - displayName: "EMS Domain"
     hawkDomain: "emsdomain"
     # Supported transport types are tibrv and tibems
     transportType: "tibems"
     # RV transport properties
     #rvService: "7474"
     #rvNetwork: ";"
     #rvDaemon: "tcp:7474"
     # EMS transport properties
     emsURL: "tcp://localhost:7222"
     emsUserName: "admin"
     emsPassword:
     bwMicroagentNameMatcher: [".*bwengine.*emsdomain.*"]
     #This pattern is matched with the BW microagent name and the name extracted from specified groups(i.e string matched in the parentheses) is used as the display name. If no group found or invalid group used we will use full microagent name.
     #Example, for "COM.TIBCO.ADAPTER.bwengine.testDomain.TestNew.Process Archive" using the below pattern, display name would be "testDomain-TestNew-Process Archive"
     bwMicroagentDisplayNamePattern: "COM.TIBCO.ADAPTER.bwengine\\.(.*)\\.(.*)\\.(.*)"
     bwMicroagentDisplayNameRegexGroups: [1, 2, 3]
     bwMicroagentDisplayNameRegexGroupSeparator: "-"

# number of concurrent tasks
numberOfThreads: 5

numberOfThreadsPerDomain: 5

#taskSchedule:
#    numberOfThreads: 1
#    taskDelaySeconds: 60

Metrics

Metrics provided by this extension are depend on the methods and metrics configured in the metrics.xml. Below is list of methods and metrics they provide.

GetMemoryUsage

GetProcessCount

GetProcessDefinitions

For each process definition following metrics are displayed

GetActivities

For each activity in each process definition following metrics are displayed

Credentials Encryption

Please visit this page to get detailed instructions on password encryption. The steps in this document will guide you through the whole process.

Extensions Workbench

Workbench is an inbuilt feature provided with each extension in order to assist you to fine tune the extension setup before you actually deploy it on the controller. Please review the following document on How to use the Extensions WorkBench

Troubleshooting

1. Please follow the steps listed in this troubleshooting-document in order to troubleshoot your issue. These are a set of common issues that customers might have faced during the installation of the extension.
2. Verify Machine Agent Data: Please start the Machine Agent without the extension and make sure that it reports data. Verify that the machine agent status is UP and it is reporting Hardware Metrics.
3. Tibco HAWK BW Microagents: Please verify that BW hawk micro agents are available using hawk display.
4. Check Logs: There could be some obvious errors in the machine agent logs. Please take a look.

Contributing

Always feel free to fork and contribute any changes directly here on GitHub.

Version

Note: While extensions are maintained and supported by customers under the open-source licensing model, they interact with agents and Controllers that are subject to AppDynamics’ maintenance and support policy. Some extensions have been tested with AppDynamics 4.5.13+ artifacts, but you are strongly recommended against using versions that are no longer supported.