Jensor 1.13 Installation Guide

Performance Engineering Research Centre
Jensor

Version 1.0
Installation Guide for Jensor 1.13
June, 2010

PERC, Gateway Park, TCS Mumbai.
Jensor 1.13 Installation Guide
ii

Document Details
Name Version
number
Description Author
Jensor Installation Guide 1.0 Describes how to use
Jensor
Suresh Malan

Document Revision List

Release Notice Reference (for release)
Revision
number
Revision date Revision
descriptio
n
Page
num
ber
Previous
page
number
Action
taken
Addenda/
New page
Release
notice
reference
1.0 24-June-2010 First
version

iii

Jensor

Jensor is free software. You can redistribute it and/or modify it under the terms of the GNU
General Public License version 2 as published by the Free Software Foundation.

This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Copyright 2008, TATA Consultancy Services (TCS)
v

About this Manual

Purpose
This manual has been written to help you understand and use the Jensor application. It presents the
installation instructions for Jensor.

Intended Audience
This manual is intended for Java Developers, Testers, Production Support personnel and Project
Managers who manage Java-based projects or products.
Pre-requisites
Following are the pre-requisites for performing the tasks presented in this manual:
Functional The reader is expected to know how to launch
installers on Windows and how to use command
line for installation on Unix platforms
Technical The reader is expected to know the following
1. Syntax to execute Java programs
2. Knowledge on how to set up / deploy the
target environment in which the Java
application will be executed.

Organisation of the Manual
Information in this manual has been organised as follows:
Table 1: Organisation of the Document
Chapter Description
Chapter 1 Provides a brief introduction to Jensor. It also details the hardware and software
requirements, and interfaces with other systems.
Chapter 2 Introduction to Jensor Architecture and usage scenarios
Chapter 3 This chapter describes procedure to install Jensor on Windows platform
Chapters 4 This chapter describes the procedure to verify successful installation on Windows
platform.
Chapter 5 This chapter describes procedure to install Jensor on Unix platform
Chapter 6 This chapter describes the procedure to verify successful installation on Unix
platform.
vi

Chapter Description
Appendix Covers Jensor Resources

Typographical Conventions
The following table gives the details of the typographical conventions used in the document:
Table 2: Typographical Conventions
Formatting
Convention
Type of Information
Key Names
Keys on the keyboard appear in title case (first letter in upper case).
For example, Page Up, Caps Lock.
A combination of keys is connected by a +. For example, Shift + Tab
means you should press the Shift key and Tab key together.
Filenames Names of files and directories are in italics. Example, System.mdb.
Command and Screen
element names
Buttons, check boxes, etc. Commands that you choose from the
menus or dialog boxes appear in title case and are bold-faced.
Example: Click Instrument from the Mode menu.
User-entered text Text that you would need to enter appears in Verdana font

Feedback and Suggestions

Send your feedback and suggestions to amol.khanapurkar@tcs.com or suresh1.malan@tcs.com
vii

Contents
1 Introduction ................................................................................................................................... 1
1.1 Introduction to Jensor ............................................................................................................................ 1
2 Introduction to Jensor Architecture ............................................................................................ 2
2.1 Usage Scenarios ................................................................................................................................... 2
2.2 Jensor Architecture ................................................................................................................................ 3
2.3 Jensor Environment ............................................................................................................................... 4
2.3.1 Software Environment ....................................................................................................................... 4
2.3.2 Hardware Environment ...................................................................................................................... 4
2.4 Additional Configuration Settings ........................................................................................................... 5
3 Installation on Windows platform ............................................................................................... 6
3.1 GUI Installer on Windows ...................................................................................................................... 6
4 Installation Verification on Windows .......................................................................................... 9
4.1 Running Demo Application .................................................................................................................... 9
5 Installation on Unix platform ..................................................................................................... 17
5.1 Command Line Installation on Unix ..................................................................................................... 17
6 Installation Verification on Unix ................................................................................................ 18
6.1 Running Demo Application .................................................................................................................. 18
Appendix .............................................................................................................................................. 26
1 Resources ................................................................................................................................................ 26

The total number of pages in this document, including the cover page, is 36.
viii

List of Figures

1. Jensor Usage Scenario
2. Jensor Architecture
3. Jensor Setup Wizard
4. Jensor Installation Folder Selection
5. Jensor Installation
6. Jensor Installation Directory Structure
7. Launching Jensor Demo Application
8. Launching Jensor UI
9. Creating Jensor Project
10. Feeding Files to Jensor for Instrumentation
11. Selectively Instrumenting Jars
12. Selecting Classes from Jar for Instrumentation
13. List of Classes to be Instrumented
14. Instrumentation completion notification
15. Jensor Demo Application in Action
16. Launching Jensor Demo Application (Unix)
17. Launching Jensor UI (Unix)
18. Creating Jensor Project (Unix)
19. Feeding Files to Jensor for Instrumentation (Unix)
20. Selectively Instrumenting Jars (Unix)
21. Selecting Classes from Jar for Instrumentation (Unix)
22. List of Classes to be Instrumented (Unix)
23. Completion of Instrumentation (Unix)
24. Jensor Demo Application in Action (Unix)
ix

List of Tables

1. Acronyms
2. Software Environment
3. Hardware Environment

x

List of Abbreviations

Abbreviation/
Acronym
Description
BCI Byte Code Instrumentation
GB
Giga Bytes
JAW
Jensor Analysis Workbench
JDF Jensor Discussion Forum
JVM Java Virtual Machine
PERC
Performance Engineering Research Center
RAM
Random Access Memory
UI User Interface
Table 1. Acronyms

1

1 Introduction
This section provides an overview of the chapter.
1.1 Introduction to Jensor
Java compilers compile Java source program into bytecode. This bytecode can be run on any JVM on
any Operating System. This is what makes Java portable. Jensor uses Byte Code Instrumentation
(BCI) techniques to collect data from the profiled application.

Using Jensor for profiling is essentially a two-step process viz.
1. Instrument Java classes or Jar files of interest.
2. Collect profiling data at runtime when the instrumented class files are executed.

Step 1, is essentially a manual process currently. Step 2 happens automatically, all that one has to do
is to place Jensor classes in application classpath.

Jensor outputs the profiling data in plain text format. Once the data is obtained, different kinds of
analysis can be performed using provided UI or writing custom programs.

2

2 Introduction to Jensor Architecture
This section describes the scenarios under which Jensor can be useful. Next it provides a high-
level architecture of Jensor.
2.1 Usage Scenarios

Fig. 1. Jensor Usage Scenario
JVM Image www.javacoffebreak.com

Jensor is designed to seamlessly scale across Dev, Test and Prod environments. After instrumenting
classes and deploying them in their respective environments, Jensor starts capturing data. The
captured data is logged to File System. Few of the captured metrics like JVM Heap consumption, Top
<N> bottleneck methods can be obtained in real-time while few metrics like Call Trace, Summary
Report etc can be obtained in offline mode.
Dev. JVM
Test. JVM
Prod. JVM
Java .class
files or Jars
Jensor
Instrument
Deploy
Deploy
Deploy
Offline
Jensor
Reports
3

2.2 Jensor Architecture
This section describes Jensor architecture

Fig. 2. Jensor Architecture

Jensor consists of 3 components
1) Instrumentation Engine This is invoked statically and consists of Byte Code Reader,
Transformer and Writer

2) Jensor Core
1
Jensor Core comes into play when instrumented code is executed. The Core
consists of 3 components
a. Log Writer for generating logs to be analyzed offline.
b. Real-Time Statistics Engine for monitoring memory consumption and identifying
bottleneck methods at run-time
c. Control Engine This controls Jensor behaviour at runtime.
d. TCP / IP Server Accepts signals to start / stop and collate Jensor data from local or
remote JAW.

3) Jensor Analysis Workbench (JAW)
2
This is invoked offline after Jensor output is obtained. It
consists currently of 9 features viz.
a. Summary Report This component crunches Jensor logs and generates Summary
Report which gives per thread per method statistics
b. Call Trace Creates entire call execution sequence with break up of response time at
each level.
c. JVM Replay Allows replay of method executions happening in JVM. This feature
can be useful in debugging reliability and scalability problems.
d. Pattern Analysis Engine This identifies patterns of interest from application
performance perspective. This component contains 2 patterns viz. Elementary and

1
Jensor Core was called Profiling Engine in Jensor version 1.1
2
Jensor Analysis Workbench (JAW) was called Analysis Engine in Jensor version 1.1
Instrumentation Engine Jensor Core

Jensor Analysis
Workbench (JAW)
Byte Code Reader
Byte Code
Transformer
Byte Code Writer
Log Writer
Real-Time Statistics
Engine
Control Engine
1. Reports
2. Call Trace
3. JVM Replay
4. Pattern Analysis
5. Charting Engine
6. Un-exited Methods
7. Tagging Engine
8. Response-Time
Spectrum
9. Object Instantiations
10. System Metrics
TCP / IP Server
4

Advance pattern analysis. Only Elementary pattern Analysis is shipped with this
version of Jensor. Advance Pattern Analysis will be distributed in later releases.
e. Charting Engine It currently provides graphical visualization for correlating method
response time histograms and memory utilization.
f. Un-exited Methods This module provides useful pointers into debugging reliability of
the application. Two modules provide information about un-exited methods.
g. Tagging Three modules in Jensor are dedicated to tagging. Tagging is the process
in which one declares Tags. Next tags are applied to technical data obtained from
Jensor. Jensor then provides break-up and visualization based on Tags. Further
more, Tags can be nested to bring out appropriate correlation between different
categories of tags. Using tags it is possible to create a business perspective of
technical data.
h. Response Time Spectrum Averages typically dilute information about response
time. This module depicts response time of all occurrences of selected methods
against wall clock time. This module enables identifying periods of the day where a
method performance degraded and by how much.
i. Object Instantiations Shows memory graph and details about object allocations
grouped by methods. This module allows one to select time range and get
information about allocated object type and allocating method along with count of
number of objects allocated. A high allocation of a particular object type within a
method can provide useful pointers to memory consumption by that method.
j. System Metrics - Shows data related to System Utilization. This module helps the
user to identify any significant changes in certain System Utilization metrics.
k. Executive Summary - This module crunches Jensor logs and generates Executive
Summary Report which gives unique methods statistics across all threads.

2.3 Jensor Environment
This section describes the hardware and software environment required to run Jensor.
2.3.1 Software Environment
Operating System
Any Operating System supporting JDK 1.4 and above
JDK / JRE version
Java 1.4 and above
Table 2. Software Environment

2.3.2 Hardware Environment
Machine Architecture
Any hardware type supporting JDK 1.4 and above
RAM
512 MB RAM recommended
CPU Speed
Intel, AMD 1+ GHz
Sun, IBM 450+ MHz
Disk Space
Minimum 2 GB Free Disk Space
Table 3. Hardware Environment

5

2.4 Additional Configuration Settings
Jensor installer for Windows creates environment variable called JENSOR_HOME. If admin rights are
not available, environment variable will need to be created manually. To create environment variable
on Windows go to Control Panel -> System -> Advanced -> Environment Variables.
JENSOR_HOME will need to be assigned value of the directory where Jensor was installed, typically
C:\Program Files\Jensor.

On Unix, add JENSOR_HOME environment variable to your profile file. JENSOR_HOME should be
assigned the value where Jensor was extracted to. For example, if you untar-ed Jensor into
/home/perf then JENSOR_HOME should be assigned the value /home/perf/Jensor. Consult your
system administrator for syntax for setting environment variables for your flavor of Unix operating
system.
6

3 Installation on Windows platform
This section provides instructions on how to install Jensor on Windows.
3.1 GUI Installer on Windows
Jensor should be installed on machine where the Java application to be profiled is running. This
application can be Standalone Java application or a web- based application. Jensor currently
supports JDK 1.4 and higher versions.

Jensor installation is a simple 2-step process. Jensor installer for Windows will guide you through the
installation process.

Step 1
The installer only asks for a location to install Jensor. Jensor installation is very compact, less than 5
MB. However it is advisable to install Jensor to a location with lot of free space available (2 GB
advisable).
Follow the procedure.
1. Click on Jensor_v19.msi
2. Click on Next

Fig. 3. Jensor Setup Wizard

3. Specify the location for Jensor Installation
7

Fig. 4. Jensor Installation Folder Selection

4. Click on Next
5. Click on Install

Fig. 5. Jensor Installation

6. Click on Finish
Step 2
8

The installer creates an environment variable called JENSOR_HOME at the location where Jensor
was installed. Ensure that this variable does not exist prior to Jensor installation. Jensor may fail to
perform correctly if JENSOR_HOME has more than one value. Suppose Jensor was installed in
C:\Program Files\Jensor\ then JENSOR_HOME gets value C:\Program Files\Jensor\

If administrative rights are not available the installer will fail to create the environment variable. The
installation can proceed however the user will manually need to create JENSOR_HOME environment
variable and assign it the location where Jensor was installed at.

Post-installation, Jensor will create the following directory structure.

Fig. 6. Jensor Installation Directory Structure

To verify value of JENSOR_HOME, you can use either of the following methods

1. Go to Run type cmd in the prompt type echo %JENSOR_HOME%
2. Go to Control Panel Go to System Properties Go to Advanced tab Go to
Environment Variables locate JENSOR_HOME in System Variables window

JENSOR_HOME should be set to value where Jensor was installed by the installer.

9

4 Installation Verification on Windows
This chapter deals with verifying successful setup of Jensor in the target environment.
4.1 Running Demo Application

Jensor ships with a sample Java2D Demo application. Java2D is developed and released as a part of
JDK by Sun MicroSystems.
Follow the steps to verify Jensor installation
1. Ensure JDK 1.4 and higher is installed and is in path. Jensor currently supports JDK 1.4 and
higher.
a. Execute the following command java version on the command prompt.
b. In first line of the output you should see Java version. Ensure that it is higher than 1.4
2. Execute sample demo application. The steps are as follows
a. Open a command prompt. Go to JENSOR_HOME\examples
b. Execute demo.bat
c. You should see a Java 2D Demo appear
10

Fig. 7. Launching Jensor Demo Application

d. Close the demo application
If you can see the Java2D application, the sample application is setup properly.
3. Go to JENSOR_HOME\bin
4. Execute startup.bat
5. You should see Jensor UI come up

Fig. 8. Launching Jensor UI

11

6. Enter perf123 as password for Administrator user
7. Go to File > New
8. Enter Project Name say Java2D

Fig. 9. Creating Jensor Project

9. You should see a folder called Java2D being created in JENSOR_HOME\projects directory.
10. Navigate to Mode > Instrument
11. Upon clicking Instrument you will see a File Dialog box. Navigate to
JENSOR_HOME\examples
12

Fig. 10. Feeding Files to Jensor for Instrumentation

12. Click Open
13

Fig. 11. Selectively Instrumenting Jars

13. Select Choose from examples\Java2Demo.jar.
14. Click Select all button on the next screen. You should see some thing like this

14

Fig. 12. Selecting Classes from Jar for Instrumentation

15. Click OK. Again Click OK.
16. You will see a list of classes that will be instrumented

15

Fig. 13. List of Classes to be Instrumented

17. Click Instrument
18. Jensor will provide notification regarding completion of instrumentation similar to figure below

Fig. 14. Instrumentation Completion Notification

19. Copy Java2Demo.jar from $JENSOR_HOME\projects\Test\instrumented folder to
JENSOR_HOME\examples folder. Overwrite existing Java2Demo.jar
20. Before proceeding further ensure that JENSOR_HOME\output directory is empty.
21. Now go back to JENSOR_HOME\examples. Execute demo.bat
22. You should now see something similar to the following screen

16

Fig. 15. Jensor Demo Application in Action

23. Play around with Java 2D application.
24. Check JENSOR_HOME\output directory. You should see 3 files viz.
a. JensorProfile.txt
b. Memusage.csv
c. topNMethods.csv
25. The file sizes will keep growing as long as the Java 2D Demo application keeps running. So
you may want to close the application after a while.
26. Once you see all 3 files in JENSOR_HOME\output directory, Jensor installation is successful.

Proceed to Jensor 1.13 Usage Manual to know further details about using Jensor in your
environment.
17

5 Installation on Unix platform
This section provides instructions on installing Jensor on Unix platform.

5.1 Command Line Installation on Unix
Jensor should be installed on machine where the Java application to be profiled is running. This
application can be Standalone Java application or a web- based application. Jensor currently
supports JDK 1.4 and higher versions. Jensor installer for unix can be used only on command line.
To take advantage of Jensor GUI, Unix server must be running X-Server.
Jensor installation is a simple 2-step process.

Step 1
Extract the Jensor tar file to a location with 2 GB free space. Although Jensor requires less than 5 MB
space for installation, it is advisable to install Jensor in location with lot of free space available.
Follow the procedure
1. Copy Jensor tar file to your Unix machine
2. Extract Jensor tar fie
3. It will create Jensor directory.
Step 2
Create an environment variable called JENSOR_HOME in your system. Follow steps required for
your Unix platform to create an environment variable. JENSOR_HOME should be set to value where
Jensor was extracted to.
Suppose Jensor tar was extracted in /home/user1 then JENSOR_HOME should be given a value of
/home/user1/Jensor. Ensure that this variable does not exist previously. Jensor may fail to perform
correctly if JENSOR_HOME has more than one value. Post-installation, Jensor will create the
following directory structure.
/home/user1/Jensor $JENSOR_HOME
| - bin
| - config
| - docs
| - examples
| - info
| - instrumentation
| - lib
| - output
| - projects
| - utilities
18

6 Installation Verification on Unix
This chapter deals with verifying successful setup of Jensor in the target Unix environment.

6.1 Running Demo Application
Jensor ships with a sample Java2D Demo application. Java2D is developed and released as a part of
JDK by Sun MicroSystems.

Follow the steps to verify Jensor installation

1. Ensure JDK 1.4 and higher is installed. Jensor currently supports JDK 1.4 and higher.
a. Execute the following command java version on the command prompt.
b. In first line of the output you should see Java version. Ensure that it is higher than 1.4
2. Execute sample demo application. The steps are as follows
a. Open a command prompt. Go to JENSOR_HOME/examples
b. Execute demo.sh
c. You should see a Java 2D Demo appear

19

Fig. 16. Launching Jensor Demo Application (Unix)
d. Close the demo application.
If you can see the Java2D application, the sample application is setup properly.
3. Go to JENSOR_HOME/bin
4. Execute startup.sh
5. You should see Jensor UI come up.

Fig. 17. Launching Jensor UI (Unix)

6. Enter perf123 as password for Administrator user
20

7. Go to File > New
8. Enter Project Name say Java2Demo

Fig. 18. Creating Jensor Project (Unix)

9. You should see a folder called Java2Demo being created in JENSOR_HOME/projects
directory.
10. Navigate to Mode > Instrument
11. Upon clicking Instrument you will see a File Dialog box. Navigate to
JENSOR_HOME/examples
21

Fig. 19. Feeding Files to Jensor for Instrumentation (Unix)

12. Click Open

22

Fig. 20. Selectively Instrumenting Jar (Unix)

13. Select Choose from examples\Java2Demo.jar.
14. Click Select all button on the next screen. You should see some thing like this

23

Fig. 21. Selecting Classes from Jar for Instrumentation (Unix)

15. Click OK. Again Click OK.
16. You will see a list of classes that will be instrumented

24

Fig. 22. List of Classes to be Instrumented (Unix)

17. Click Instrument
18. Jensor will provide notification regarding completion of instrumentation similar to figure below

Fig. 23. Instrumentation Completion Notification (Unix)

19. Copy Java2Demo.jar from JENSOR_HOME/projects/Test/instrumented folder to
JENSOR_HOME/examples folder. Overwrite existing Java2Demo.jar
20. Before proceeding further ensure that JENSOR_HOME/output directory is empty.
21. Now go back to JENSOR_HOME/examples. Execute demo.sh
22. You should now see something similar to the following screen
25

Fig. 24. Jensor Demo Application in Action (Unix)

23. Play around with Java 2D application.
24. Check JENSOR_HOME/output directory. You should see 3 - 5 files viz.
a. JensorProfile.txt
b. Memusage.csv
c. topNMethods.csv
d. ObjectInst.txt
e. SystemUtilization.txt
25. The file sizes will keep growing as long as the Java 2D Demo application keeps running. So
you may want to close the application after a while.
26. Once you see all 3 files in JENSOR_HOME/output directory, Jensor installation is successful.
Proceed to Jensor 1.13 Usage Manual to know further details about using Jensor in your
environment.

Confidential 26

Appendix
1 Resources
Jensor-related blogs may be found at http://www.tcsinnovations.com

Performance Engineering Research Center (PERC), TCS has also released a WAN Emulator on
Sourceforge.net named WANem at http://wanem.sourceforge.net. WANem helps you emulate WAN /
Internet environment inside a LAN environment.

Jensor 1.13 Installation Guide

Încărcat de

Informații document

Drepturi de autor

Formate disponibile

Partajați acest document

Partajați sau inserați document

Opțiuni de partajare

Vi se pare util acest document?

Este necorespunzător acest conținut?

Drepturi de autor:

Formate disponibile

Jensor 1.13 Installation Guide

Încărcat de

Drepturi de autor:

Formate disponibile

Performance Engineering Research Centre

S-ar putea să vă placă și