JIRA Documentation

JIRA 6.4.x
JIRA 6.0 Documentation
JIRA 5.2 Documentation
JIRA 5.1 Documentation
More...
 

 

Search the Knowledge Base and Documentation Spaces

You're visiting the JIRA Knowledge Base. Visit the JIRA Knowledge Base Home for an overview.

Skip to end of metadata
Go to start of metadata

Due to security vulnerabilities which were fixed in JIRA 4.1.1, the 'manageyourkitprofiling.jsp' file used in the procedures on this page is no longer available nor functional in JIRA version 4.1.1 and later. Furthermore, you will no longer be able to download this file from this page.

For more information, refer to the JIRA 4.1.1 Upgrade Guide.

Contents

Using YourKit for Diagnosing Performance Issues

YourKit is a commercial Java profiling tool that allows to generate CPU and Memory profiles of running applications with no noticeable overhead. The profiling libraries of YourKit are free to use and redistribute. The console used to analyze the generated snapshots requires a commercial license to run.

If your JIRA instance seems to be running quite slowly or is utilizing too much memory (you are seeing OutOfMemoryErrors in log files), then generating a CPU or Memory profile can provide valuable insight into your running instance. Generating one of these snapshots and attaching the result to a JIRA support issue can help our support staff get to the bottom of some of the more nasty issues which are lurking out there.

This document will guide you in configuring JIRA to run with the YourKit profiler agent enabled.

Installation and Usage

In order for YourKit to be able to generate CPU and Memory profiles, it must hook into the JVM which is running JIRA. To make the agent library accessible to the JVM you will need to do the following:

Windows
  1. Download the attached files yjpagent.dll and yjp.ini. Save them to c:\windows\system32 on the machine where JIRA is running (this seems to be the only directory the Windows Service picks them up from).
  2. Test that the agent can be found by opening a Command Prompt and running java -agentlib:yjpagent=help (assuming JDK 1.5):
  3. Add the startup option -agentlib:yjpagent=onexit=memory,dir=/path/to/write/snapshots. See Setting Properties and Options on Startup.
  4. Test that memory profiles are being written by starting and stopping JIRA. When the service is stopped, it should pause while a *.memory file is written to the specified directory.
Linux
  1. Download the attached file libyjpagent.so. Save this file to a directory in the machine where JIRA is running (eg. /home/youruser/yourKitAgent).
  2. Include the directory in which you saved the file into your LD_LIBRARY_PATH. (NOTE: you do not need to do this for your global environment, it is only needed in the environment from which you start JIRA). You can modify this by setting and exporting the variable LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/youruser/yourKitAgent.
  3. If you are running JIRA Standalone, you can set this up by modifying the {PATH TO STANDALONE}/bin/setenv.sh file and adding a line that looks like:
  4. Add the startup option -agentlib:yjpagent=onexit=memory,dir=/path/to/write/snapshots. See Setting Properties and Options on Startup.
  5. Test that memory profiles are being written by starting and stopping JIRA. When the service is stopped, it should pause while a *.memory file is written to the specified directory.

Managing YourKit

Now that you have setup the YourKit agent and made certain that the jsp and jar files are correctly configured in JIRA you are ready to start managing Memory and CPU snapshots. If you browse to http://<YOUR JIRA>/secure/admin/manageyourkitprofiling.jsp you will see the following:

The page gives you two options, Memory Profiling and CPU Profiling.

Memory Profiling

At any point you can click the 'Take a Memory Snapshot' link and this will generate a memory snapshot of the application at that moment. This function can take a few seconds to complete and will slow JIRA down while executing. You should see a message like: Successfully generated a memory snapshot to: /home/detkin/snapshots/snapshots-2006-08-16.memory please attach this file to a support request. once it has completed. The JIRA support team should inform you as to the times when they would like to to get a memory snapshot from the running application.

If you run into situations where JIRA is unresponsive and you are not able to navigate to the JSP to trigger a memory snapshot, please ensure that you start JIRA with the onexit=memory parameter (as discussed in the JIRA:above section) and simply shutdown JIRA. Before shutting down a memory snapshot will be created.

CPU Profiling

To generate a CPU snapshot you need to 'Start CPU Recording'. This tells the YourKit profiler that it should start keeping track of the CPU information. If at any time you decide you want to stop the CPU recording, but not take a snapshot all you need to do is click the 'Stop CPU Recording' link. To take a CPU snapshot you need to have started the CPU recording and when you want to take the snapshot just click the 'Take a CPU Snapshot' link. This will generate the snapshot and automatically stop the CPU recording. When completed you should see a message like: Successfully generated a cpu snapshot to: /home/detkin/snapshots/snapshots-2006-08-16.cpu please attach this file to a support request. Generating a CPU snapshot does not take as long as generating a memory snapshot.

There will be a slow down

CPU profiling does not come with out a cost. There is an overhead that will slow the system down. This is best used to profile individual requests. E.g.

  1. Start CPU Profiling
  2. Perform an Issue Navigator Search
  3. Create a Snapshot

Do not leave running for a long time!