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.

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. All the BW hawk methods are configured in metrics.xml file in TibcoHawkMonitor/conf
  4. Replace the jars in lib with the jars from your Tibco BW installation. In BW 5.9 all the jars are available in tibrv folder.
  5. Restart the Machine Agent.

Configuration

config.yaml

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

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.*"

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
Metric path is typically: Application Infrastructure Performance|<Tier>|Custom Metrics|Tibco BW| followed by the individual categories/metrics below:

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. 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
  2. config.yml: Validate the file [here] (http://www.yamllint.com/)
  3. Tibco HAWK BW Microagents: Please verify that BW hawk micro agents are available using hawk display.
  4. Metric Limit: Please start the machine agent with the argument -Dappdynamics.agent.maxMetrics=5000 if there is a metric limit reached error in the logs. If you dont see the expected metrics, this could be the cause.
  5. Check Logs: There could be some obvious errors in the machine agent logs. Please take a look.
  6. Collect Debug Logs: Edit the file, /conf/logging/log4j.xml and update the level of the appender com.appdynamics to debug Let it run for 5-10 minutes and attach the logs to a support ticket

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.

Community

Find out more in the AppSphere community.

Support

For any questions or feature request, please contact AppDynamics Center of Excellence.

 

Version:

1.0.0

Compatibility:

3.7+

Java:

1.7+

Last Update:

25 Oct 2017

 

 

 Changes in versions:
1.0.0: Initial release