Download the YourKit agent for your OS (see the links at the bottom of the page).
上次更新時間
2021年4月29日
|
亦適用於 Communiqué
Issue
How do I configure YourKit Java profiler to work with CQ3.x or CQ4.x?
Solution
Install YourKit
-
-
Install the YourKit profiler.
-
Start the YourKit profiler (JDK 1.5 is necessary to run the profiler).
- Windows: Launch "YourKit Java Profiler" from in the Start menu.
- Linux, Solaris: Run YourKit Java Profiler Home > /bin/yjp.sh.
- Mac OS X: When the downloaded application is unzipped, click its icon.
Enable profiling
It's possible to enable profiling directly in an IDE or even J2EE server. However, it can be better to enable profiling manually to be independent of IDE or J2EE servers. The procedure differs from OS to OS.
| OS | Action |
|---|---|
| Windows, 32-bit Java | add <!YourKit Java Profiler Home>\bin\win32 to the PATH |
| Windows, 64-bit Java | add <!YourKit Java Profiler Home>\bin\win-amd64 to the PATH |
| Mac OS X | add <!YourKit Java Profiler Home>/bin/mac to the DYLD_LIBRARY_PATH |
| Linux x86, 32-bit Java | add <!YourKit Java Profiler Home>/bin/linux-x86-32 to the LD_LIBRARY_PATH |
| Linux AMD64, 64-bit Java | add <!YourKit Java Profiler Home>/bin/linux-amd64 to the LD_LIBRARY_PATH |
| Solaris SPARC, 32-bit Java | add <!YourKit Java Profiler Home>/bin/solaris-sparc-32 to the LD_LIBRARY_PATH |
| Solaris SPARC, 64-bit Java | add <!YourKit Java Profiler Home>/bin/solaris-sparc-64 to the LD_LIBRARY_PATH |
| Solaris x86, 32-bit Java | add <!YourKit Java Profiler Home>/bin/solaris-x86-32 to the LD_LIBRARY_PATH |
| Solaris x86, 64-bit Java (AMD64) | add <!YourKit Java Profiler Home>/bin/solaris-x86-64 to the LD_LIBRARY_PATH |
Check the profiler agent
To check that Java can load the profiler agent, you can call the following command that prints a description of agent parameters:
- Java 5 or 6
- java -agentlib:yjpagent=help
- Java 1.3 or 1.4
- java -Xrunyjpagent:help
Integrate the agent library in application
To be able to profile a Java application, it is necessary to provide the YourKit tool an interface to the Java application. You integrate the YourKit agent library into the JVM where the target application you want to profile is running. First, enable profiling by providing the path to the respective OS agent library where the JVM is running on (see Enabling Profiling). Include setting environment variables in the start-script of your application.
For example, in a CQ start script under Linux, do the following:
#--------------------------------------------------------------------- # enables the YourKit Java Profiler #--------------------------------------------------------------------- YJP_HOME="/home/honwai/yjp-6.0.16/bin/linux-x86-32" export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$YJP_HOME
This setting makes the agent library available to the JVM. Now it is a matter of telling the JVM to actually integrate this library, which differs according to the JVM version in use:
| Java Version | JVM Option |
|---|---|
| 1.3/1.4 | java -Xrunyjpagent |
| 5 or newer | java -agentlib:yjpagent |
Now you're ready to start your application and the actual profiling. The agent library prints some information to the standard output (in case of CQ it is server(logs/startup.log):
[YourKit Java Profiler 6.0.16] Using JVMPI (Linux; 32 bit JVM)
[YourKit Java Profiler 6.0.16] *** HINT ***: Use Java 5 (or newer) when possible!
[YourKit Java Profiler 6.0.16] Profiler agent is listening on port 10001...
Hint: In CQ 4.2, the serverctl script has become more advanced, allowing for providing various options on startup. It includes the option to start the JVM with the YourKit agent library. Setting the above described env variables is still mandatory, but setting the additional JVM option is not:
linuxbox:/opt/day/cq-4.2/server# ./start --profile
To get a complete list of the available options, type ./serverctl and you get a list of all available options.
Connecting with YourKit profiler to application
When starting an application with profiling enabled, the agent library chooses a free port that is available on the system. It is not necessary to know the port. The YourKit tool can automatically connect to a running profiled application, either locally or remotely. If it finds more than one application, you are prompted to select a particular one.
It is also possible to specify a dedicated port if local security settings (for example, firewall) don't allow for arbitrary ports to be chosen. See the following table for a complete list of options that can be passed to the agent library.
Agent library options
| Option | Description |
|---|---|
| disablealloc | (Java 5 and newer / JVMTI only) Don't instrument bytecode with instructions needed for object allocation recording. |
| disablecounts | (Java 5 and newer / JVMTI only) Don't instrument bytecode with instructions needed for CPU tracing. Only CPU sampling is available. |
| disablej2ee | (Java 5 and newer / JVMTI only) Don't instrument bytecode with instructions needed for J2EE profiling. |
| sampling | Launch Java application with CPU sampling turned on. You do not have to profile CPU right from the start. Instead, in many cases you'd better start or stop the measuring later from the user interface or using Profiler API. |
| tracing | Launch Java application with CPU tracing turned on. You do not have to profile CPU right from the start. Instead, in many cases, you'd better start or stop the measuring later from the user interface or using Profiler API. This option cannot be used in combination with 'disablecounts'. |
| noj2ee | Don't perform J2EE high-level profiling. This option only affects CPU profiling started with 'sampling' or 'tracing'. |
| alloc | Launch Java application with started object allocation recording. All objects are recorded. You do not have to record allocations right from the start; instead, you can start or stop recording later from the Profiler or using Profiler API. This option cannot be used in combination with 'disablealloc'. |
| allocadaptive | Launch Java application with started object allocation recording. As many objects as possible are recorded, keeping overhead at moderate level. You do not have to record allocations right from the start; instead, you can start or stop recording later from the Profiler or using Profiler API. This option cannot be used in combination with 'disablealloc'. |
| usedmem=<percent> | Automatically capture memory snapshot when used heap memory reaches the threshold. |
| onexit=memory | Always capture memory snapshot on exit. CPU snapshot iscaptured automatically if CPU profiling is enabled when the profiled application exits. |
| onexit=telemetry | Capture telemetry snapshot on exit. This option is automatically used when the profiled application is started from the IDE. |
| port=<value> | Specify port that the profiler agent listens on for communication with the Profiler. By default any free port is chosen. |
| onlylocal | Allow only local connections to profiled application |
| dir=<directory for="for" snapshots="snapshots"> | Specify directory where snapshots are created. By default, <user home="home">/Snapshots directory is used. |
| quiet | Suppress diagnostics messages that the profiler agent prints to the console. |
| help | Print short description of agent parameters. |
Separate multiple options with commas. Pay attention that Java requires : after -Xrunyjpagent but = after -agentlib:yjpagent.
Examples (Java 5 or newer):
java -agentlib:yjpagent FooClass java -agentlib:yjpagent=onexit=memory,dir=c:\MySnapshots FooClass java -agentlib:yjpagent=usedmem=70 FooClass
Examples (Java 1.3/1.4):
java -Xrunyjpagent FooClass java -Xrunyjpagent:onexit=memory,dir=c:\MySnapshots FooClass java -Xrunyjpagent:usedmem=70 FooClass
Documentation
Once the YourKit profiler is installed, there's extensive HTML documentation in the installation directory, in <!YourKit Java Profiler Home>/docs/help/index.html. It explains in detail how to integrate the agent library on the target application that is the subject of profiling. It also provides many useful options that can be passed to the agent. For example:
- generate a heap-dump once the application exits
- generate a heap-dump once a certain threshold is reached
These options can be found in <!YourKit Java Profiler Home>/docs/help/agent.html.
The current 7.0 release doesn't come with documentation, you can find it on our setup server:
- \\setup\install\profiling\yjp-6.0\docs\help\index.html
