This page last changed on Jun 14, 2009 by rosie@atlassian.com.

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. If you run into any troubles with this guide please look at the troubleshooting guide.

Confluence also has a plugin to profile Confluence's memory and CPU usage with YourKit.

Make profiler agent library accessible to the Java Virtual Machine

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

On Windows

  • 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). Test that the agent can be found by opening a Command Prompt and running java -agentlib:yjpagent=help (assuming JDK 1.5; see below for 1.4):

On Linux

  • Download the attached file libyjpagent.so. Save this file to a directory in the machine where JIRA is running (eg. /home/youruser/yourKitAgent).
  • 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.
  • 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:
    LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/home/youruser/yourKitAgent
    export LD_LIBRARY_PATH
    

Make the JVM running JIRA use the YourKit Agent

General Information

Once you have made the library accessible to the JVM you need to add some JVM parameters that tells the JVM to use the Yo agent.

Java applications all start by running a command

java <args>

where <args> varies. To include the YourKit agent in the running JVM, you must add a JVM parameter. The form of the parameter depends on your Java version.

If you are running JIRA with Java 1.3 or 1.4, use -Xrunyjpagent parameter:

E.g., java -Xrunyjpagent <args>

If you are using Java 5.0 (1.5), use -agentlib:yjpagent parameter:

E.g., java -agentlib:yjpagent <args>

-Xrunyjpagent or -agentlib:yjpagent has additional options. In most cases there's no need to use them.

The options are comma separated: -Xrunyjpagent[:<option>, ...] or -agentlib:yjpagent[=<option>, ...].

To generate snapshots from a running JIRA instance the only required option is 'dir'. When snapshots are taken they will be written to the path specified by the 'dir' option on the machine where JIRA is running.

If JIRA is running out of memory (you are seeing OutOfMemoryError in the logs) it is recommended that you set the 'onexit=memory' option. This will generate a memory snapshot when the JVM is exiting, even if JIRA does not respond and appears hung.

Eg. to profile the application and have it write the profile snapshots to /path/to/write/snapshots while running a 1.3 or 1.4 JVM, run

java -Xrunyjpagent:onexit=memory,dir=/path/to/write/snapshots <args>

Eg. to profile the application and have it write the profile snapshots to /path/to/write/snapshots while running a 1.5 JVM, run

java -agentlib:yjpagent=onexit=memory,dir=/path/to/write/snapshots <args>

Please take careful notice of the difference in syntax between the -Xrunyjpagent:onexit=memory,dir=/path/to/write/snapshots and -agentlib:yjpagent=onexit=memory,dir=/path/to/write/snapshots. Specifically notice that the arguments in the Xrunyjpagent are started by a : and that the arguments in the agentlib:yjpagent are started by a =.

If you are using 1.5 JVM to run JIRA, please use the -agentlib:yjpagent parameter. Using -Xrunyjpagent with JVM 1.5 appears to start up fine, but can result in errors while JIRA is running.

Configuring Application Server

JIRA is run in an application server (Tomcat, Orion, Websphere, Weblogic, JBoss etc), and these app servers usually have scripts wrapping the actual java call. The -Xrunyjpagent parameter that is discussed above, is usually passed into these scripts through an environment variable.

JIRA Standalone as a Windows Service

If you are running JIRA Standalone, as a Windows Service (recommended), you will need to set the parameter by running:

tomcat5 //US//JIRA ++JvmOptions="-agentlib:yjpagent=onexit=memory,dir=c:\atlassian-jira-enterprise-3.6.5-standalone\logs"

(specify the correct path to the logs directory)

Test that memory profiles are being written by starting and stopping the service. When the service is stopped, it should pause while a *.memory file is written to the specified directory.

If you don't see the .memory file being created, make sure the directory you specified is the logs directory inside Tomcat. Other directories would not work for me. Generating the memory dump generally seemed flakey, with dumps occasionally failing on the first service restart and then succeeding, or the service shutdown hanging and needing to be shut down twice.

For more information on setting JVM parameters when running as a Windows Server please see JIRA documentation).

JIRA Standalone on Windows (started with startup.bat)

If you are running JIRA Standalone, on Windows, then you can set this up by modifying the {PATH TO STANDALONE}\bin\setenv.bat file and adding a line that looks like:

set JAVA_OPTS=%JAVA_OPTS% -agentlib:yjpagent=onexit=memory,dir=c:\atlassian-jira-enterprise-3.6.5-standalone\logs

(assuming JDK 1.5; specify the correct path to your logs directory)

JIRA Standalone on Linux

If you are running JIRA Standalone, on Linux, then you can set this up by modifying the {PATH TO STANDALONE}/bin/setenv.sh file and adding a line that looks like:

JAVA_OPTS="-Xrunyjpagent:onexit=memory,dir=/home/detkin/snapshots $JAVA_OPTS"
Other Application Servers

For help setting this up in other application servers please see this page.

Including the jsp and jar file in your JIRA instance

Once you have configured the JVM running JIRA to enable the YourKit agent and have correctly configured the 'dir' option, you need to take steps to allow you to generate profiling snapshots from within JIRA. This is a simple process of making certain that a jar file is available to JIRA and that a jsp is included in the JIRA administration section.

You can manage the generation of CPU and Memory profiling snapshots via the JIRA administration section.

JIRA Version Action
Prior to 3.7
3.7 - 3.8.1 This version ships with an older version and will need to be replaced.
3.9 or greater JIRA now ships with the latest version of this file

You will also need to include the YourKit jar into your instance of JIRA:

After making certain that the jsp is included and that the jar file has been put into the correct place you will need to restart your instance of JIRA. You should now be able to browse to http://<YOUR JIRA>/secure/admin/manageyourkitprofiling.jsp and you should see a screen that looks like the image in the next section. If instead you see an error please read through the troubleshooting section.

Manage profiling from JIRA administration section

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 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!


yjp.ini (application/octet-stream)
yjpagent.dll (application/octet-stream)
libyjpagent.so (application/octet-stream)
yjp-controller-api-redist.jar (application/x-jar)
screenshot.jpg (image/jpeg)
manageyourkitprofiling.jsp (application/octet-stream)
yjpworking.png (image/png)
yjpagent.dll (application/x-msdos-program)
yjp.ini (application/octet-stream)
libyjpagent.so (application/octet-stream)
yjp-controller-api-redist.jar (application/x-jar)
manageyourkitprofiling.jsp (application/octet-stream)
libyjpagent.so (application/octet-stream)
Document generated by Confluence on Oct 06, 2009 00:26