How to use SUPA (Single User Performance Analysis)

Tool for plain Tomcat Performance Measurements

Contents
Contents .................................................................................................................................................. 1
Introduction ............................................................................................................................................. 3
Prerequisites ............................................................................................................................................ 3
General .............................................................................................................................................................3
Exclusive system access .....................................................................................................................................3
Only for remote systems: SSH and operating system user for host on which Tomcat runs ....................................3
Only for remote systems: Firewall settings .........................................................................................................3
Create folder c:\tmp as destination for the garbage collection log file .................................................................3
Share path to garbage collection log (e.g. c:\tmp) ...............................................................................................3

Performance Measurement of Tomcat using SUPA (default KPIs) .............................................................. 4

Start Tomcat with JMX support and GC logging enabled .....................................................................................4
Start SUPA as a javaw process (only required if Tomcat runs on same host like SUPA) .........................................4
Configure SUPA for a measurement ...................................................................................................................4
Perform a measurement ....................................................................................................................................7
Interpret the numbers .......................................................................................................................................7

Troubleshooting ....................................................................................................................................... 8

Version History & Changes

Date

Change

Author

06.08.2015

First version of document

Fabian Schlarmann

You will find an up-to-date version of this document linked on the SUPA Wiki page:
https://go.sap.corp/SUPA (short link)
https://wiki.wdf.sap.corp/wiki/display/NWEngPer/SUPA (direct link)

Introduction
SUPA offers the possibility to measure different SAP technology stacks out of the box, using the built-in configuration
editor. In contrast to that, measuring the performance of an application running on a Tomcat server requires some
manual steps. This document describes in detail, how SUPA can be configured to receive performance counters like
CPU time consumption, Java memory (processing space) and http server response times from a Tomcat server running on a MS Windows host.

Prerequisites
General
The reader shall be familiar with elementary terms and principles of performance measurements. A basic understanding how SUPA works is assumed. Further documentation is available below https://wdf.sap.corp/SUPA.

Exclusive system access

Performance measurements of applications running on Tomcat require an exclusive access to the Tomcat server. No
other user should access the Tomcat while performance measurements are in progress.
Background: As Tomcat as such does not deliver detailed performance statistics based on request level, it can only be
monitored as a whole (aka black box approach). That means the monitoring of Tomcat is done on process level only.
As a consequence, the resource consumption of singly user actions cannot be isolated from the load on the whole
Tomcat server, but only Tomcat global values can be grabbed.

Only for remote systems: SSH and operating system user for host on which Tomcat runs
Tomcat can either run on the same host as SUPA or on a remote host. If Tomcat and SUPA are operated in the same
host, you can skip this paragraph, as the folloing only applies if Tomcat is operated on a remote host.
During the measurement, SUPA has to grab performance data from the remote host on which Tomcat runs. To do so,
SUPA connects via SSH to the remote system. Hence, the following two preconditions are required:

The remote host must be reachable via SSH, or in other words, an SSH client has to be installed and started
on the remote host

An operating system user on the remote host must be available to enable SUPA establishing an SSH connection to the remote host

Only for remote systems: Firewall settings

As SUPA connects via JMX to the Tomcat process in order to gather Java heap memory related information, the used
ports must not be blocked by any firewall between the measurement PC (on which SUPA runs) and the Tomcat host.
As JMX uses the defined port just for the initial connection, and then switches to a randomly chosen one, blocked
ports can become an issue for the measurement.

Create folder c:\tmp as destination for the garbage collection log file
In order that the Java VM can write garbage collection related information to the gclog.txt file, make sure that the
path c:\tmp (or whatever else is defined in the environment variables) exists. If the folder does not exist, just create
it.

Share path to garbage collection log (e.g. c:\tmp)

Share the folder in which the gclog.txt is written. The default path as it is used in this document is c:\tmp, so name
the share tmp.

Performance Measurement of Tomcat using SUPA (default

KPIs)
Start Tomcat with JMX support and GC logging enabled
Measuring the processing space of a web application running on Tomcat requires that SUPA is able to access memory
related data via JMX and that it can read information on garbage collection (GC) activity from a log file. Therefore
Tomcat needs to be started with both JMX access and GC logging enabled. To enable it open a command prompt and
change to the Tomcat bin directory. Set the following environment variables in the command prompt:
SET ENABLE_JMX=-Dcom.sun.management.jmxremote Dcom.sun.management.jmxremote.authenticate=false Dcom.sun.management.jmxremote.port=54321 -Dcom.sun.management.jmxremote.ssl=false
SET ENABLE_GCLOG=-XX:+PrintGCDetails -XX:+PrintGCTimeStamps -Xloggc:c:\tmp\gclog.txt XX:+UseParNewGC -verbose:gc
SET JAVA_OPTS=%ENABLE_JMX% %ENABLE_GCLOG%

The commands set the JMX port to 54321, you could change that to any other available port on your system. Just
make sure to adjust this setting in the SUPA configuration later. The same is true for the path of the gclog.txt file,
where all garbage collection related activated is logged into.
Start Tomcat from within the opened command prompt, e.g. via startup.bat.

Start SUPA as a javaw process (only required if Tomcat runs on same host like SUPA)
This paragraph describes how to modify the start command of SUPA for a measurement of a Tomcat server running
on the same host like SUPA does. If Tomcat is operated on a different (remote) host, this paragraph can be skipped.
1. Make a copy of the file supa.bat and name it supa_javaw.bat
2. To edit supa_javaw.bat, open it in a text editor
\bin\java
with
\bin\javaw
%HOME%\sapjvm8\bin\java %COMMON_ARGS% -jar supaStarter.jar %*

3. Replace

in

line

4. Save and close the file

The described steps describe a pragmatic approach to ensure that the process names of SUPA and Tomcat are not the
same (default: both java.exe; after the change: SUPA: javaw.exe, Tomcat: java.exe).

Configure SUPA for a measurement

This paragraph describes how to create a configuration for SUPA to measure the performance of applications running
on Tomcat. It is assumed that the process of Tomcat is named java.exe (default name).
1. Chose the appropriate scenario and copy the corresponding configuration keys to a text file. Save it to your
local disk:
a. Tomcat and SUPA run on the same host:
branch.0.name = tomcat_local
branch.0.data.provider =
com.sap.nw.performance.supa.core.dataprovider.ProcessCpuTimeDataProvider,c
om.sap.nw.performance.supa.core.dataprovider.ProcessingSpaceProvider
branch.0.j2ee.hostname = localhost
branch.0.j2ee.jmx.port = 54321
branch.0.j2ee.gc.logfile = c:\\tmp\\gclog.txt
branch.0.component.class =

com.sap.nw.performance.supa.gui.base.config.landscape.model.components.Gen
ericProcess
branch.0.component.id = tomcat_local
branch.0.component.name = tomcat_local
branch.0.cputime.hostname = localhost
branch.0.cputime.process = java
branch.0.cputime.os = Windows
branch.0.cputime.ssh.user =
branch.0.cputime.ssh.password =
data.provider =
com.sap.nw.performance.supa.core.manager.BranchManager,com.sap.nw.performa
nce.supa.core.dataprovider.ScreenshotDataProvider
scenario.name = tomcat performance
Save the configuration keys into a text file named tomcat_localhost.properties.

b. Tomcat runs on different Windows host than SUPA

branch.0.name = tomcat_remote_windows
branch.0.data.provider =
com.sap.nw.performance.supa.core.dataprovider.ProcessCpuTimeDataProvider,c
om.sap.nw.performance.supa.core.dataprovider.ProcessingSpaceProvider
branch.0.j2ee.hostname = <enter remote host name>
branch.0.j2ee.jmx.port = 54321
branch.0.j2ee.gc.logfile = \\\\<remote host name>\\tmp\gclog.txt
branch.0.component.class =
com.sap.nw.performance.supa.gui.base.config.landscape.model.components.Gen
ericProcess
branch.0.component.id = tomcat_remote
branch.0.component.name = tomcat_remote
branch.0.cputime.hostname = <enter remote host name>
branch.0.cputime.process = java
branch.0.cputime.os = Windows
branch.0.cputime.ssh.user = <operating system user remote host>
branch.0.cputime.ssh.password =
data.provider =
com.sap.nw.performance.supa.core.manager.BranchManager,com.sap.nw.performa
nce.supa.core.dataprovider.ScreenshotDataProvider
scenario.name = tomcat performance

Replace the placeholder <remote host name> with the actual remote host name. The other yellow
marked keys can be changed later within SUPA. Save the configuration keys into a text file named
tomcat_windows_remote.properties.
c. Tomcat runs on a Linux host, SUPA on a Windows host
In general works like for Windows, but the environment variables for Tomcat (see Start Tomcat with
JMX support and GC logging enabled) have to be set differently. Additionally, select Linux instead of
Windows in step 6.
2. Start SUPA via supa_javaw.bat (SUPA and Tomcat run on same host) or via supa.bat (SUPA and Tomcat run on
different hosts)
3. Start a manual measurement

4. Load the configuration file created in step 1. into SUPA. For tomcat.localhost.properties, the configuration
could now be finished or adjusted. For the remote cases, the obligatory adjustments are described in the next
steps

5. (Optional)

Adjust

the

scenario

name,

and

if

applicable,

add

scenario

step(s)

6. Navigate to the next screen and open the Tomcat configuration (only applicable for remote cases). Replace
the placeholder for OS user and OS Password by providing an operating system user and password to connect
to
the
remote
system.
Confirm
with
Ok.

7. (Optional) Configure additional components like a client

8. Go to next and check the details given in the summary, e.g.:

9. Confirm with finish and save the configuration below the same name as the original one, e.g.
tomcat_localhost.properties

Perform a measurement
Start and stop measurements with the corresponding buttons as usual. Remember, that the whole Tomcat server is
measured, rather than single user interactions. Therefore, keep measurements intervals as short as possible (i.e. do
not wait 10 seconds after a user interaction was finished).

Interpret the numbers

SUPA measures performance KPIs on Tomcat as global values; i.e. all activity taking place during a measurement, be it
initiated from the test user, from some other user or from the system itself, will be reflected in the measured numbers. Therefore, always make sure to exclusively use the Tomcat while the measuring is executed.
The most interesting KPIs are the AS Java processing space and the Process(es) CPU Time. The following table provides an explanation for those two KPIs. All the other KPIs are explained in detail in the documentation, which is part
of each SUPA delivery. Also see links below in this document.
KPI

Performance
quirement

Standard

Re- Description

AS Java processing space [B]

PERF-7: Consumed Memory

AS Java processing space is the heap difference between stop and start of measurement plus the amount of freed memory
by GC while the measurement was running.

Process(es) Cpu Time [ms]

PERF- 8: CPU Time

Process(es) Cpu Time is the sum of differences in CPU Time for all specified processes between stop and start of a meas-

urement; for the special case Tomcat,. the

Process(es) CPU Time reflects the amount
of CPU Time consumed by the Tomcat (java.exe) process.
For full details of other measured performance counters, refer to the documentation which is part of each SUPA delivery, or below the following links:
\\dwdf207\nw_e_perf\performance_tools\Software\Supa\docu\dataprovider.html#process.cpu
\\dwdf207\nw_e_perf\performance_tools\Software\Supa\docu\dataprovider.html#processing.space

Troubleshooting
If you face the issue that SUPA cannot to the gclog.txt file, try to access the share manually in Windows Explorer. If
you are asked for a user/password, provide it in the upcoming credentials dialog. Then, retry to measure with SUPA.