Purpose of Document
This document is meant as a quick start guide to setting up using the IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter. It provides a step by step guide for installing the plug-in, how to include it in a JMeter test script, and provides a brief overview of the functionality available through the plugin.
The information available in this document was validated using:
- IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter version 1.2
- Apache JMeter version 2.6
- IBM Cognos TM1 version 10.1
- IBM Cognos TM1 version 10.2
Note that the plug-in may or may not work with versions of Apache JMeter or IBM Cognos TM1 other than those listed above. Using other versions of these products may result in limited functionality.
Exclusions and Exceptions
This document outlines setup instructions and an overview of the functionality available in the IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter. It does not cover Apache JMeter or IBM Cognos TM1 beyond their immediate relationship to the plug-in.
An IBM Cognos TM1 installation must be present and available for real-time monitoring of the TM1 server to take place. This document also assumes a certain level of familiarity from the user with Apache JMeter.
The IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter is a plugin for the Apache JMeter performance testing tool. It allows its user to monitor TM1 server activity in real-time while running an Apache JMeter performance test or to view and analyze existing TM1Top log files.
One of the advantages of the plug-in is that it can represent the content of a TM1Top capture in different ways (such as grids, graphs, timelines or as a summary), which provides the user with more insight as to what is happening on the TM1 server. It also allows the user to scroll through time on the whole capture, allowing them to quickly locate and analyze a particular point of interest.
Installing the plug-in
In order to use the IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter, a copy of the Apache JMeter performance testing tool is required. This tool can be downloaded from The Apache Software Foundation website (see the Resources section at the end of this document) and can be installed/deployed in the directory of your choosing. We will hereby refer to this directory as <jmeter_root>.
- Copy the com.ibm.cognos.jmeter.tm1.top.visualizer JAR file into the <jmeter_root>/lib/ext directory. This will install the core components for the plug-in, including the Classic viewer.
- Copy the com.ibm.cognos.tm1.api.wrapper JAR file into the <jmeter_root>/lib directory. This will allow the plug-in to monitor server activity in real-time, and is required to run.
- Copy the TM1JavaApi JAR file from the TM1 installation into the <jmeter_root>/lib directory. This file is typically found under the <tm1_install>/bin/classes directory.
- Add the Applix certificate to the Java keystore, by following the instructions found in the IBM Technote at http://www.ibm.com/support/docview.wss?uid=swg21414527. This is necessary for real-time monitoring.
- Additional viewers can also be installed by copying their respective JAR files into the <jmeter_root>/lib/ext directory. The following viewers are included with the TM1 Server Monitor Plug-in for Apache JMeter install kit:
- Analysis viewer
- Graph viewer
- Summary viewer
- Timeline viewer
- Analysis viewer
Note that some of these viewers may override existing user settings. To uninstall a specific viewer, you can remove the JAR file from the specified directory, and restart JMeter.
Adding the plug-in to an Apache JMeter script
In order to use the IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter, it needs to be added to a JMeter script. To add the plug-in to a script, follow the instructions below.
- Launch Apache JMeter and open the desired script.
- From the tree, locate the node to which the listener is to be added.
- Right-click on the node and from the context menu, select Add > Listener > IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter.
The plug-in is now part of the Apache JMeter script.
Monitoring TM1 Server activity without running a JMeter load test
There may be cases where you want to monitor TM1 server activity without necessarily running a JMeter load test (for example, on a server with live users). In such cases, you need to build a simple script to get JMeter to run long enough to capture results. One way to create such a script is detailed below.
- Launch Apache JMeter.
- Right-click on the Test Plan and from the context menu, select Add > Threads (Users) > Thread Group.
- In the Thread Group, you can tick the Loop Count: Forever checkbox to capture results for an undetermined amount of time. Please note that capture results may be kept in memory, and as such, the amount of memory made available to JMeter may need to be increased (how to do this is outside the scope of this document).
- Right-click on the Thread Group and from the context menu, select Add > Sampler > Java Request.
- Right-click on the Java Request and from the context menu, select Add > Timer > Constant Timer.
- Edit the Constant Timer’s Thread Delay (in milliseconds) value to match how long you want the capture to take place.
- Right-click on the Test Plan and from the context menu, select Add > Listener > IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter.
You now have a simple JMeter script that can be used to monitor TM1 server activity without an actual JMeter load test.
Capturing results in real-time
Before any attempt is made to monitor a TM1 server in real-time, the Applix certificate needs to be added to the Java keystore. Please see the Installing the Plug-in section of this document for more details.
Once the certificate has been added, follow the steps below to set up the plug-in to monitor a TM1 server.
- In the Settings tab, set the appropriate adminhost, servername, and refresh values as you would when launching the TM1Top utility, where
- adminhost is the name or IP address of the machine on which the TM1 server is running
- servername is the name of the TM1 server to be monitored
- refresh is the interval, in seconds, at which the polling is to take place
- In the Write results to file / Read from file section, enter the name of a file to which you wish to write the output. This step is optional. If you do not provide a file name, the results will not be written to a file and will be lost when JMeter is closed or when the listener states are cleaned.
- In the Write results to file / Read from file section, you can toggle the Keep All Data in Memory checkbox if it’s available. This step is optional. By selecting this option, all of the captured data will be kept in memory, which will result in optimal performance. Deselecting this option will result in the captured data being temporarily written out to disk. This can be useful when working with limited memory, but may affect performance. Note that some viewers may override/disable this option for performance reasons. Currently, only the Analysis viewer overrides the option.
Start the Apache JMeter test. Note that since this plug-in is a JMeter listener, it will only monitor the TM1 server for as long as the Apache JMeter script is running.
Reading from an existing TM1Top log file
The IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter is also able to read existing capture files that are either generated by the plug-in itself, the TM1Top utility, or the IBM Cognos TM1 Operations Console.
To load an existing capture file, follow the instructions below.
- In the Write results to file / Read from file section, if the Keep All Data in Memory checkbox is available you have the option to toggle it on and off.
- In the Write results to file / Read from file section, click on the Browse button to access the capture file that you wish to load. Load time will depend on the size of the file, and whether data needs to be written to temp files.
The file will load and you will be able to manipulate the results. Note that only files generated by the products enumerated above are supported. If the file has been modified by an external tool, it may not be loaded properly.
Using the plug-in
The IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter contains some helpful features that can be used to analyze TM1Top information, whether it is captured in real-time or read from a log file. A brief overview is given below.
The slider (Figure 1) can be used to scroll through time to see the different capture points (snapshots), making it easier than ever to navigate through large quantities of data.
Figure 1: Snapshot slider, located directly under the Write results to file / Read from file section
Thread breakdown bar
The thread breakdown bar (Figure 2) updates as the slider is moved, and gives a visual representation of thread distribution by state for the currently selected point in time. The colours map to the legend that is always visible below the viewer panel.
Figure 2: The thread breakdown bar, located under the slider
In addition to letting you specify the TM1 server information when monitoring activity in real-time, the Settings tab (Figure 3) also offers the ability to select the TM1Top capture mode, as well as to sort and filter the data based on preference.
Figure 3: The Settings tab
The TM1Top mode will determine what is to be logged when performing the capture. In Classic mode, the information available on TM1 servers running a version earlier than 10.1 RP1 will be returned. When attempting to connect to such a TM1 server, only this mode would work. The Enhanced mode will display additional information available in TM1 10.1 RP1 and is the recommended capture mode. Finally, the Detailed mode extends what is available in the Enhanced mode by displaying more information about locking scenarios but be aware that it may introduce some performance overhead.
Any sorting and filtering done through the Settings tab will be applied on the fly to any viewer that supports it. Some viewers may also offer the ability to override these settings locally, which means that other viewers would remain unaffected.
There are multiple viewers available to display the TM1Top data from different angles. These viewers can be installed individually, so that you can pick and choose what you really want to use. Please see the Installing the plug-in section of this document for more details.
The Analysis viewer can be used to filter data based on a specific username, state, function name, or any combination of the three. This provides the ability to easily focus on certain subsets of the data. Note that this viewer requires all data to be kept in memory.
The Classic viewer displays the data in a similar way as the TM1Top utility. The data is colour-coded to make it a bit more readable, and can be sorted and filtered. The Classic viewer is part of the core IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter package.
The Graph viewer displays a thread breakdown by thread state for the whole capture as a line graph. This can be used to quickly see at which points there was more activity or contention on the server. It also provides the ability to quickly jump to a specific point in time by clicking on a point of interest on the graph.
The Summary viewer displays metrics related to thread breakdown by thread state, concurrency, as well as the longest running and waiting threads for any specific point in time. It also provides the ability to quickly jump to a specific point in time by clicking on specially highlighted timestamps.
The Timeline viewer displays server activity by each thread over the last 15 snapshots from the currently selected one - essentially showing the evolution of activity over a short period of time. More details can be gathered by hovering the mouse over a given activity point.
|TM1 plugin for Apache JMeter performance testing.||tm1-server-monitor-plugin-1_2-dropin-for-apache-jmeter.zip||353KB|