AppDynamics Monitoring Extension for use with Tibco Hawk

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 is preconfigured with Tibco BW microagent methods.

This extension works only with the standalone machine agent.

Note : By default, the Machine agent and AppServer agent can only send a fixed number of metrics to the controller. This extension potentially reports thousands of metrics, so to change this limit, please follow the instructions mentioned here.

Prerequisites

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.

Installation

  1. Unzip TibcoHawkMonitor-<version>.zip into <machine_agent_dir>/monitors/
  2. Edit config.yaml file in TibcoHawkMonitor/conf and provide the required configuration (see Configuration section)
  3. Configure BW hawk methods in metrics.xml file in TibcoHawkMonitor/conf
  4. Add the following Tibco jars, console.jar,console_agent_shared.jar,talon.jar,tibrvj.jar,util.jar,jms.jar,security.jar,tibcrypt.jar,tibjms.jar,tibrvjms.jar to lib folder. In BW 5.9 all the jars are available in tibrv folder.
  5. Set system variables like RV_HOME, PATH and LD_LIBRARY_PATH. For more information take a look at this document
  6. Restart the Machine Agent.

Configuration

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

  1. Edit the file config.yml located at <MachineAgent_Dir>/monitors/ The metricPrefix of the extension has to be configured as specified here. Please make sure that the right metricPrefix is chosen based on your machine agent deployment, otherwise this could lead to metrics not being visible in the controller.
  2. ParamDescriptionExample
    displayNameDisplay name for the hawk domain"Domin 1"
    hawkDomainBW Hawk domain from which we are trying to get the stats from"testDomain"
    rvServiceRV service to use to connect to hawk"7474"
    rvNetworkRV network to use to connect to hawk";"
    rvDaemonRV daemon to use to connect to hawk"tcp:7474"
    bwMicroagentNameMatcherregex matcher to match and autodetect the BW hawk microagents".*bwengine.*"
  3. 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:


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: 2

numberOfThreadsPerDomain: 5

taskSchedule:
    numberOfThreads: 1
    taskDelaySeconds: 60

#This will create this metric in all the tiers, under this path
#metricPrefix: "Custom Metrics|Tibco BW|"

#This will create it in specific Tier/Component. Make sure to replace  with the appropriate one from your environment.
#To find the  in your environment, please follow the screenshot https://docs.appdynamics.com/display/PRO42/Build+a+Monitoring+Extension+Using+Java
metricPrefix: "Server|Component:|Custom Metrics|Tibco BW"

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

MetricDescription
TotalBytesTotal number of bytes allocated to the process engine.
FreeBytesTotal number of bytes that are not currently in use.
UsedBytesTotal number of bytes that are currently in use.
PercentUsedPercentage of total bytes that are in use.

GetProcessCount

MetricDescription
TotalRunningProcessesTotal number of currently executing process instances.

GetProcessDefinitions

For each process definition following metrics are displayed

MetricDescription
CreatedNumber of process instances created for this process definition.
SuspendedNumber of times process instances have been suspended.
SwappedNumber of times process instances have been swapped to disk.
QueuedNumber of times process instances have been queued for execution.
AbortedNumber of times process instances have been aborted.
CompletedNumber of process instances that have been successfully completed.
CheckpointedNumber of times process instances have executed a checkpoint.
TotalExecutionTotal execution time (in milliseconds) for all successfully completed process instances.
AverageExecutionAverage execution time (in milliseconds) for all successfully completed process instances.
TotalElapsedTotal elapsed time (in milliseconds) for all successfully completed process instances.
AverageElapsedAverage elapsed clock time (in milliseconds) for all successfully completed process instances.
MinElapsedElapsed clock time (in milliseconds) of the process instance that has completed in the shortest amount of elapsed time.
MaxElapsedElapsed clock time (in milliseconds) of the process instance that has completed in the longest amount of elapsed time.
MinExecutionExecution time (in milliseconds) of the process instance that has completed in the shortest amount of execution time.
MaxExecutionExecution time (in milliseconds) of the process instance that has completed in the longest amount of execution time.
MostRecentExecutionTimeExecution time (in milliseconds) of the most recently completed process instance.
MostRecentElapsedTimeElapsed clock time (in milliseconds) of the most recently completed process instance.
TimeSinceLastUpdateTime (in milliseconds) since the statistics have been updated.
CountSinceResetNumber of process instances that have completed since the last reset of the statistics.

GetActivities

For each activity in each process definition following metrics are displayed

MetricDescription
ExecutionCountNumber of times the activity has been executed.
ElapsedTimeTotal clock time (in milliseconds) used by all executions of this activity. This includes waiting time for Sleep, Call Process, and Wait For... activities.
ExecutionTimeTotal clock time (in milliseconds) used by all executions of this activity. This does not include waiting time for Sleep, Call Process, and Wait For... activities.
ErrorCountTotal number of executions of the activity that have returned an error.
LastReturnCodeStatus code returned by most recent execution of this activity. This can be either OK, DEAD, or ERROR.
MinElapsedTimeElapsed clock time (in milliseconds) of the activity execution that has completed in the shortest amount of elapsed time.
MaxElapsedTimeElapsed clock time (in milliseconds) of the activity execution that has completed in the longest amount of elapsed time.
MinExecutionTimeExecution time (in milliseconds) of the activity execution that has completed in the shortest amount of execution time.
MaxExecutionTimeExecution time (in milliseconds) of the activity execution that has completed in the longest amount of execution time.
TimeSinceLastUpdateTime (in milliseconds) since the statistics have been updated.
ExecutionCountSinceResetNumber of activity executions that have completed since the last reset of the statistics.

Troubleshooting

  1. Please look at the troubleshooting document and make sure that everything is followed correctly.
  2. Tibco HAWK BW Microagents: Please verify that BW hawk micro agents are available using hawk display.

Workbench

Workbench is a feature by which you can preview the metrics before registering it with the controller. This is useful if you want to fine tune the configurations. Workbench is embedded into the extension jar.

To use the workbench

  • Follow all the installation steps
  • Start the workbench with the command
  java -jar /path/to/MachineAgent/monitors/TibcoHawkMonitor/tibco-hawk-monitoring-extension.jar
  This starts an http server at http://host:9090/. This can be accessed from the browser.
  • If the server is not accessible from outside/browser, you can use the following end points to see the list of registered metrics and errors.
    #Get the stats
    curl http://localhost:9090/api/stats
    #Get the registered metrics
    curl http://localhost:9090/api/metric-paths
  • You can make the changes to config.yml and validate it from the browser or the API
  • Once the configuration is complete, you can kill the workbench and start the Machine Agent

Contributing

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

Compatibility

Version:

1.0.0

Compatibility:

3.7+

Java:

1.7+

Last Update:

25 Oct 2017

 

 

 Changes in versions:
1.0.0: Initial release
1.0.1: Adding licence files