Performance Snapshot without Yourkit Plugin

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.

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.

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:

1. Open http://yourkit.com/download/index.jsp

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

3. License key is not required for our purpose! Do not request evaluation license. (Unless you intend to do an evaluation of YourKit, of course.)

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

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.

1. Find out which profiler agent to use.

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

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

2. Edit setenv script:

   1. 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):

      set JVM_SUPPORT_RECOMMENDED_ARGS=-agentlib:%~dp0..\profiler\bin\win64\yjpagent=port=10001,onlylocal,dir=%~dp0..\profiler\snapshots,delay=20000 -XX:MaxPermSize=500m

   2. 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):

      JVM_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"

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

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

5. Stop JIRA and start it again.

6. Watch <jira_install>/logs/catalina.out for YourKit message like [YourKit Java Profiler 9.5.6] Loaded.

Now you can proceed to #Running Profiling Session.

Attach Profiler Agent to JIRA without Restarting

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.

1. Find out the process ID of the process that runs JIRA. You can use jps command from the Java distribution.

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

3. Change current directory to <jira_install>/profiler/yjp-9.5.6. (You may have a different version of yjp.)

4. Run the following command, substituting JIRA process ID instead of PID.

   1. On Windows:

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

   2. On other OS:

The command should output something like this:

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:

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.

CPU Performance Analysis

If JIRA is unresponsive or burns CPU extensively, you can run CPU analysis session.

1. Start session with the following command:

2. Let JIRA work for some time. If needed, take a specific action that causes the problem to manifest.

3. Stop session and record a 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:

1. Use any FTP client (ftp or lftp from the command line).

2. Connect to host f.almworks.com

3. Use login name almftp and password almftp

4. Upload files to the root folder.

5. After the upload is finished, please send us an e-mail with a notification that you have uploaded the 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.