IBM Business Analytics Proven Practices: IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter

Product(s): IBM Cognos TM1, Apache JMeter; Area of Interest: Infrastructure

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.

François DeGuire, Software Developer, IBM

François DeGuire is a software developer for IBM's Performance Management group, and has been working out of the IBM Canada Lab in Ottawa since 2008. Over the years, he has been involved in the design and implementation of a variety of tools and products in different areas of the IBM Business Analytics division.



21 March 2014

Introduction

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.

Applicability

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.

Assumptions

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.


Overview

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
      (com.ibm.cognos.jmeter.tm1.top.visualizer.viewer.analysis.jar)
    • Graph viewer
      (com.ibm.cognos.jmeter.tm1.top.visualizer.viewer.graph.jar)
    • Summary viewer
      (com.ibm.cognos.jmeter.tm1.top.visualizer.viewer.summary.jar)
    • Timeline viewer
      (com.ibm.cognos.jmeter.tm1.top.visualizer.viewer.timeline.jar)

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.


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.

Slider

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
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
Figure 2: The thread breakdown bar, located under the slider

Settings tab

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

Viewers

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.

Analysis viewer

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.

Classic viewer

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.

Graph viewer

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.

Summary viewer

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.

Timeline viewer

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.


Download

DescriptionNameSize
TM1 plugin for Apache JMeter performance testing.tm1-server-monitor-plugin-1_2-dropin-for-apache-jmeter.zip353KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics
ArticleID=966366
ArticleTitle=IBM Business Analytics Proven Practices: IBM Cognos TM1 Server Monitor Plug-in for Apache JMeter
publish-date=03212014