JIRA 4.0 : Profiling Memory and CPU usage with YourKit
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.
Make profiler agent library accessible to the Java Virtual MachineIn 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
On Linux
Make the JVM running JIRA use the YourKit AgentGeneral InformationOnce 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>
Configuring Application ServerJIRA 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 ServiceIf 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.
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 LinuxIf 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 ServersFor help setting this up in other application servers please see this page. Including the jsp and jar file in your JIRA instanceOnce 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.
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 sectionNow 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 ProfilingAt 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 ProfilingTo 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.
![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() ![]() |
![]() |
Document generated by Confluence on Oct 06, 2009 00:26 |