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:

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

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.

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

      CODE

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

      CODE

      
      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.

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.

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:

      CODE

      
      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:

      CODE

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

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.

1. Start session with the following command:

   CODE

   
   java -jar yjp-controller-api-redist.jar localhost 10001 start-cpu-sampling
   

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:

   CODE

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

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.

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.