Issue

How do I configure YourKit Java profiler to work with CQ3.x or CQ4.x?

Solution

Install YourKit

  1. Download the YourKit agent for your OS (see the links at the bottom of the page).

  2. Install the YourKit profiler.

  3. 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

Denna produkt är licensierad enligt en Creative Commons Erkännande-Ickekommersiell-Dela Lika 3.0 Unported-licens  Twitter™- och Facebook-inlägg omfattas inte av villkoren i Creative Commons-licensen.

Juridiska meddelanden   |   Onlinesekretesspolicy