Performance Snapshot without Yourkit Plugin
Performance Profile allows Tempo support team to analyze performance-related problems on your JIRA server without direct access to it.
We are using Java Profiler product called YourKit. In order to collect the profile, you'll need to download freely distributed "agent" library, connect it to your JIRA instance and capture a performance snapshot. You will need to purchase a license from YourKit only if you want to analyze the captured profile yourself.
No special knowledge is required to collect the performance profile, but being familiar with using the command-line on the server that runs JIRA helps.
Download Profiling Agent
Download the ZIP with profiling agent from here: jira-profiler-v1-yjp956.zip md5sum e3ea2b72ef4b22584c641425275050d0
Unpack the downloaded ZIP file into the directory where you have JIRA installed (not JIRA home!). This will create <jira_install>/profiler
directory under your JIRA installation path.
You can unpack the profiler into any other directory, but this instructions and our scripts assume that the profiler is unpacked into JIRA install dir.
If you will be able to restart JIRA before profiling, this is all you need — you can proceed to restarting JIRA with Profiling.
Additional Download to Profile JIRA Without Restart
If you need to profile JIRA without restarting it first (and assuming it is not already started with a profiler agent), you will need to download full distribution of the YourKit Java Profiler:
Click on ZIP Archive type of download - NOT the installer! ZIP archive is typically downloaded under "Solaris" section - it is the correct link even if you run JIRA on Windows.
License key is not required for our purpose! Do not request evaluation license. (Unless you intend to do an evaluation of YourKit, of course.)
Unpack the downloaded ZIP into
<jira_install>/profiler
– this is the directory created at step 1. Unpacking will create a sub-directory there - for example,<jira_install>/profiler/yjp-9.5.6
.
Restart JIRA with Profiling
If you need to profile without restart, skip this step.
The following instruction is provided for a standalone JIRA installation.
To restart JIRA with profiling, you need to pass additional options to Java that runs JIRA. This is done by editing <jira_install>\bin\setenv.bat
on Windows or <jira_install>/bin/setenv.sh
on a Unix-based OS and pointing Java to a profiler agent that you have unpacked at step 1.
Find out which profiler agent to use.
Look into
<jira_install>/profiler/bin
directory. Typically there will be two sub-directories for your operating system: 32-bit and 64-bit. The bitness must match the bitness of JVM that runs JIRA. You can verify which Java your JIRA runs on if you open Administration | System Info in JIRA and look for "Java VM". If it mentions "64-Bit", then JIRA runs on a 64-bit Java.Note the name of the subdirectory under
profiler
directory that corresponds to the bitness of target JVM: it may be win64 or linux-x86-32 or something like that.
Edit
setenv
script:On Windows, set or append the following parameters to
JVM_SUPPORT_RECOMMENDED_ARGS
in<jira_install>\bin\setenv.bat
(following is a single long line):CODEset JVM_SUPPORT_RECOMMENDED_ARGS=-agentlib:%~dp0..\profiler\bin\win64\yjpagent=port=10001,onlylocal,dir=%~dp0..\profiler\snapshots,delay=20000 -XX:MaxPermSize=500m
On other OS, set or append the following parameters to
JVM_SUPPORT_RECOMMENDED_ARGS
in<jira_install>/bin/setenv.sh
(following is a single long line):CODEJVM_SUPPORT_RECOMMENDED_ARGS="-agentpath:`dirname \"$0\"`/../profiler/bin/linux-x86-64/libyjpagent.so=port=10001,onlylocal,dir=`dirname \"$0\"`/../profiler/snapshots,delay=20000 -XX:MaxPermSize=500m"
Note that in the lines above, you should change win64 or linux-x86-64 to the name of the directory where the correct profiler agent for your OS/Java is located.
You may also need to change port=10001 to make profiling agent listen on some other TCP port - in case port 10001 is already taken.
Stop JIRA and start it again.
Watch
<jira_install>/logs/catalina.out
for YourKit message like [YourKit Java Profiler 9.5.6] Loaded.
Use Copy & Paste to copy the parameters and then edit them in the setenv.sh
If the parameters are set incorrectly, JIRA start may fail. Verify that you have specified the agent directory correctly. Also verify that <jira_install>
directory path does not contain spaces.
Profiler agent will use directory <jira_install>/profiler/snapshots
to write performance snapshots - it must be write-accessible to the JIRA process.
Now you can proceed to #Running Profiling Session.
Attach Profiler Agent to JIRA without Restarting
If you have restarted JIRA with profiling, skip this step.
If possible, restart JIRA with profiling instead of attaching profiler agent on the fly.
You will need the full distribution of YourKit downloaded at step 1.1. You will need to run a Java program as specified below - with the same version of Java that JIRA runs on. We assume that it is in your PATH variable in the command-line, but if it's not - you need to specify a full path to java
.
Find out the process ID of the process that runs JIRA. You can use
jps
command from the Java distribution.Find out the location of JDK (Java Development Kit). If you don't have JDK installed (only JRE), this procedure won't work. Typically JDK home is stored in the command-line environment variable JAVA_HOME.
Change current directory to
<jira_install>/profiler/yjp-9.5.6
. (You may have a different version of yjp.)Run the following command, substituting JIRA process ID instead of PID.
On Windows:
CODEjava -cp lib\yjp.jar;%JAVA_HOME%\lib\tools.jar com.yourkit.Main -attach PID port=10001,onlylocal,dir=<jira_install>\profiler\snapshots
Replace <jira_install> with the full path of the JIRA installation folder.
On other OS:
CODEjava -cp lib/yjp.jar:$JAVA_HOME/lib/tools.jar com.yourkit.Main -attach PID port=10001,onlylocal,dir=`pwd`/../snapshots
The command should output something like this:
Attaching to process 60108 using options port=10001,onlylocal,dir=..\snapshots
The profiler agent has attached. Waiting while it initializes...
The agent is loaded and is listening on port 10001.
You can connect to it from the profiler UI.
Running Profiling Session
To successfully run a profiling session, you need to have JIRA running with a profiling agent, as explained above. The agent does not add much overhead when being idle — it sits there waiting for your commands to start a profiling session.
General Procedure
The profiling session is controlled by sending commands to the profiling agent (within the JIRA process). The program that is used to send the commands is yjp-controller-api-redist.jar
, located in <jira_install>/profiler
. The common format for running this program is:
java -jar yjp-controller-api-redist.jar localhost 10001 <command>
The <command> is replaced with some actual command, and if you changed the default port of the agent from 10001 to something else, you need to specify that port number here instead of 10001. This command should be run from <jira_install>/profiler
directory.
We are assuming that java
is on your PATH. If not the case, use the full path to java
executable.
CPU Performance Analysis
If JIRA is unresponsive or burns CPU extensively, you can run CPU analysis session.
Start session with the following command:
CODEjava -jar yjp-controller-api-redist.jar localhost 10001 start-cpu-sampling
Let JIRA work for some time. If needed, take a specific action that causes the problem to manifest.
Stop session and record a snapshot:
CODEjava -jar yjp-controller-api-redist.jar localhost 10001 capture-performance-snapshot
Sending the Snapshots to Support Team
By default, snapshots are written into <jira_install>/profiler/snapshots
directory. Locate it and create a ZIP archive of all relevant snapshot files. If the ZIP is less than 10 Megabytes, it's ok to send it to us by e-mail.
If the ZIPPed snapshot is 10 MB or larger, you need to use FTP to send it over to us:
Use any FTP client (
ftp
orlftp
from the command line).Connect to host
f.almworks.com
Use login name
almftp
and passwordalmftp
Upload files to the root folder.
After the upload is finished, please send us an e-mail with a notification that you have uploaded the snapshots.
You will not be able to list or download files from that FTP, and your FTP client may show errors about that. That's ok and should not prevent you from uploading snapshots.
After Profiling Session
You may want to continue running JIRA with the profiling agent loaded, since it does not product much overhead. Make sure you have stopped all the monitoring.
For a safer / cleaner environment, you can restart JIRA with the profiling options in setenv
script commented out.