What platforms, Java versions and technologies are supported?

Profiling is supported on the following platforms:

• Windows NT/2000/2003/XP/Vista, 32-bit Java and 64-bit Java (AMD64)
• Linux, 32-bit Java (x86) and 64-bit Java (AMD64)
• Mac OS X 10.4 and newer
• Solaris SPARC, 32-bit and 64-bit Java
• Solaris 10 x86, 32-bit and 64-bit Java

Supported Java technologies:

The following kinds of Java applications can be profiled:

• J2SE
• J2EE
• J2ME (memory)
• Applets

Supported Java versions:

Profiled applications can run Java 1.3.0 or higher.

Please note that some features require more recent Java versions.

Please also note that the profiler UI itself requires Java 5 or 6. The appropriate Java version can be downloaded from:

• Windows/Linux/Solaris: http://java.sun.com/javase/downloads/index.jsp
• Mac OS X: http://www.apple.com/support/downloads/javaformacosx104release5.html

Important: We strongly do not recommend using Java 5 earlier than update 5 (1.5.0_05) because of JVM bugs that can crash profiled applications. In Java 5 update 5 and newer these JVM bugs are fixed.

Supported Java vendors:

At the moment, the profiler supports profiling on:

• Sun Java: versions 1.3, 1.4, 5, 6, as well as 7 early access
• BEA JRockit 5 and 6 (see comments...)
• IBM Java 5 SR1 and newer (see comments...)

How big is the profiling overhead?

Profiler may add some overhead to the profiled application's performance. This overhead may vary from zero to significant, depending on conditions such as current profiling mode and Java version. Read more...

Can I profile my J2EE server?

You can automatically enable profiling in a number of popular application servers with the help of "Tools | Integrate with J2EE Server...".

To enable profiling in a server that "Tools | Integrate with J2EE Server..." does not currently support, please manually perform some simple steps.

If you encounter problems while configuring a particular application and the documentation fails to provide an answer, please contact us at support@yourkit.com.

Is BEA JRockit VM supported?

The following BEA JRockit JVMs are supported:

• JRockit 5 R27.1.0 or newer; download at http://commerce.bea.com/products/weblogicjrockit/5.0/jr_50.jsp
• JRockit 6 R27.1.0 or newer; download at http://commerce.bea.com/products/weblogicjrockit/60/jr_60.jsp

Is IBM VM supported?

IBM Java 5 Service Release 1 (SR1) or newer is supported

Use 'java -version' command to check if the version is appropriate:

java version "1.5.0"
Java(TM) 2 Runtime Environment, Standard Edition (build pwi32pdev-20060919a (SR3))
IBM J9 VM (build 2.3, J2RE 1.5.0 IBM J9 2.3 Windows XP x86-32 j9vmwi3223-20060919 (JIT enabled)
J9VM - 20060915_08260_lHdSMR
JIT  - 20060908_1811_r8
GC   - 20060906_AA)
JCL  - 20060919

"J9VM" date (see text in bold) should be "20060220" or later.

I get an Out of Memory error when capturing memory snapshots

The cause and possible solutions depend on the version of JVM you are using to profile your Java applications.

When capturing a memory snapshot, JVM of version 1.3/1.4 can crash with an error like this:

Exception java.lang.OutOfMemoryError: requested 291955644 bytes for unsigned char in
D:/BUILD_AREA/jdk142-update/ws/fcs/hotspot\src\share\vm\prims\jvmpi.cpp. Out of swap space?

The problem is that Java versions earlier than 5 were, by design, not capable of capturing memory snapshots for big heaps. The actual size may differ depending on the kind of objects in the heap, but in our experience, the limit is usually 1 Gb.

Technically, the out of memory error happens when the JVM internally allocates a continuous block of memory and fills it with heap data, to pass it to a profiler. The size of memory needed for this temporary structure can be compared with the size of the heap.

This problem cannot be solved in 1.3/1.4 JVMs.

Possible workarounds:

• Use Java 5 or 6 if possible. Even if Java 1.3/1.4 is a customer requirement and thus you cannot easily upgrade, we'd recommend considering to profile in development with a newer JVM. In most cases, performance problems are not JVM-specific (bottleneck when running an application with Java 6 will also be a bottleneck when running with Java 1.3), thus the profiling results and following optimizations of the application code will also be effective when the application runs in production with an older JVM.
• Decrease the heap size (-Xmx) when profiling. In most cases, dumping works fine with heaps smaller than 1 Gb.
• Click "Force garbage collection" several times before capturing a memory snapshot. This will reduce the peak memory amount required for successful snapshot capture (Java 1.3/1.4 allocates temporary structures for non-accessible objects too).

When a memory snapshot is being captured, objects in the heap are temporarily "tagged" with 8-byte numbers. JVMTI, the profiling API of Java 5 and newer, provides all heap data in terms of these tags. The mapping is stored inside JVM in some JVM internal data structures. When JVM fails to allocate memory for these structures, it terminates with an error.

A profiler agent doesn't have the means to reliably predict the lack of memory to prevent the JVM crash.

This problem is mostly a problem of 32-bit JVMs, that have limited virtual memory available (2-4 Gb, depending on the OS and virtual memory settings).

Possible workarounds:

• Use 64-bit JVM if possible.
• Decrease the heap size (-Xmx) when profiling.

• Use Java 6 and utilize its built-in heap dumper. The dumper produces files in HPROF format, fully supported by YourKit Java Profiler. The dumper is a part of JVM and requires almost no additional memory resources to make the dump, because it accesses the heap data structures directly, unlike profiler agents that use higher-level APIs to access the Java heap. The built-in dumper doesn't do any tagging.

  To dump heap with the built-in dumper, you can use 'jmap' command line tool (located in <JDK dir>/bin). To dump the heap to file, issue the command:

  jmap -dump:format=b,file=<full file name>.hprof <PID>

  To learn the PID (process identifier of running JVM), you can use 'jps' or 'jconsole' utilities.

• If you use YourKit Java Profiler 6.x or older, please try YourKit Java Profiler 7.0. In this version, the peak memory usage for temporary data structures has been dramatically reduced, compared with older versions.

I get an Out of Memory error when opening a huge memory snapshot

While opening huge memory snapshots, the profiler UI may run out of memory. "Huge" usually means around 1 Gb, but the exact numbers vary in each particular case, depending on snapshot specifics. When this happens, you get the corresponding error message.

This is mostly a problem when you run the profiler UI on a 32-bit system.

The best solution is to run the profiler UI on a 64-bit system:

• 64-bit systems do not have the 2-4 Gb memory size limitation of 32-bit systems. Snapshot of virtually any size can be successfully loaded and analyzed if there is enough physical memory.
• Running the profiler UI on a 64-bit system doesn't require you to change the environment where your profiled applications run. So if your profiled applications run on a 32-bit system and you cannot or do not want to change this, then you don't have to. It only matters that the profiler UI itself runs on 64-bit system; it will let you analyze results gathered on either 32 or 64-bit machines.
• You can get an "Out of memory error" on a 64-bit system, too. This may happen because the default heap size limit for the profiler UI (512M) is not enough in some cases. If this happens, simply change the -Xmx to a bigger value, as suggested in the error message. Usually, 64-bit systems have enough physical and virtual memory, so the problem should be solved. Note: even if the system is 64-bit, it can contain both 32 and 64-bit JVMs. Please make sure you use the appropriate one (e.g. make the corresponding change in yjp.sh).

If you cannot use a 64-bit system, there are workarounds that may help you load huge snapshots on a 32-bit system.

• Try tweaking the -Xmx value.

  The profiler UI is a Java program and stores its data in the Java heap. In addition, for efficiency, some parts of a snapshot file are also mapped directly to the virtual memory outside the Java heap.

  Thus Java heap (limit controlled by -Xmx) and the memory outside it (the rest of the memory available for the process) are competitors on a 32-bit system and together must not exceed its 2-4 Gb virtual memory limit.

  If you make -Xmx too big or too small, the snapshot may not fit.

  So, please pay attention to what error message you get:

  • If you get "Out of memory" error, please increase the -Xmx value to make the Java heap bigger
  • If you get "Not enough virtual memory", please decrease the -Xmx value to make the Java heap smaller

  Once again, you wouldn't need to do such tweaking running the profiler UI on a 64-bit system, as described above.

• Try to make snapshots smaller by running the profiled application with a smaller Java heap limit (-Xmx setting of the profiled application). If the profiled application has a smaller heap, then the resulting snapshots will in general be smaller in size, will take less memory to load, and will allow faster analysis in the UI. Usually it's OK to run profiled applications with smaller heaps in order to perform performance analysis; optimizations based on such profiling will still be relevant when the same application runs with a bigger heap (e.g. in production).

How to capture snapshots periodically?

Please read this help topic.

Eclipse plugin is installed, but "Profile" menu items are still disabled

• If you use a pre-released version of Eclipse 3.2 or 3.3 (a milestone, a daily build etc.), please use the release version instead.
• Eclipse 3.4 (a milestone, a daily build):
  • use the latest available milestone build
  • if you encounter problems with the latest milestone build, please report your issue to the forums or to support@yourkit.com.
• Eclipse 3.2 only: make sure you have enabled the "Profile" action group in Eclipse under "Window | Customize Perspective | Commands"
• This can be an issue of Eclipse plugin caching. To clean up the cache, please restart Eclipse with -clean in the command line.

• Only if you use YourKit Java Profiler 5.x or older: make sure Eclipse PDE is installed.

  PDE can be absent if Eclipse was not installed from the entire Eclipse SDK (e.g. installed only Platform Runtime Binary + JDT). Without PDE, the plugin will not function. If needed, download PDE at http://www.eclipse.org/downloads/. Upgrading to YourKit Java Profiler 6.0 or newer will also help.

I've got message "Error occurred during initialization of VM. Could not find agent library on the library path or in the local directory: yjpagent"

If you manually configured the command line of the profiled application, please make sure you have made profiler agent library accessible to the Java Virtual Machine. (Read more about enabling profiling manually.)

In particular, make sure you select the directory that corresponds to your platform and the appropriate 32 or 64-bit agent version.

On Linux, make sure you appropriately use 32 or 64-bit libraries: bin/linux-x86-32 vs. bin/linux-amd64. For example, pay attention that even if your Linux is 64-bit, you may use 32-bit JVM, that needs 32-bit agent version.

On Solaris, make sure you use an appropriate platform (SPARC or x86) and a 32 or 64-bit agent version. Even if Solaris is 64-bit, you may use 32-bit JVM. In that case, the 32-bit agent should be used: solaris-<platform>-32 instead of solaris-<platform>-64. To use 64-bit JVM, add -d64 JVM parameter to the command line.

Another possible reason is that profiler agent library cannot be linked because it depends on other libraries not installed on your system. To see if that is the case, please:

• cd <YJP Home>/bin/platform
• ldd libyjpagent.so

If ldd shows non satisfied dependences, please try to resolve them by installing the missing shared libraries.

I've got message "Error occurred during initialization of VM. Could not find -Xrun library: libyjpagent.so"

See similar issue.

I've got message "OutOfMemory Permgen space"

This may be related to Sun Java bug 5093520.

Because of this bug under some conditions applications started with any JVMTI agent on Java 5.0 may run out of memory if they intensively load and unload classes via custom class loaders.

This bug has been fixed in Java 5 update 7 and Java 6.

I've got message "FATAL ERROR in native method: Bad global or local ref passed to JNI"

This message is completely harmless. It results from Sun Java bug 6221510.

To avoid it, please remove JVM parameter "-Xcheck:jni".

Profiled application hangs on startup. What could be the reason?

The possible reason is that there are Java debug options specified that suspend JVM until debugger connects to it (-Xrunjdwp:...suspend=y).

What kind of GC root is "Held by JVM"/"Other"?

If an object is reported as a root of the kind "Held by JVM" (called "Other" in older versions of the profiler), this means that the JVM protects it from garbage collection for its own internal purposes.

Actually, the list of such objects depends on JVM implementation. Possible known cases are:

• the system class loader
• a few important exception classes which the JVM knows about
• a few pre-allocated objects for exception handling
• custom class loaders when they there are in process of loading classes

Unfortunately, JVM provides absolutely no additional detail for such objects. Thus it becomes the analyst's responsibility to decide under which case a certain root falls.

Also, there were bugs in JVM such that some objects were illegally held by JVM as this kind of roots, causing memory leaks in applications actively loading/unloading classes. We strongly recommend always using the latest Java versions and maintenance updates.

Java 1.3 note: In snapshots created under JDK 1.3.x, a kind of GC roots such as local variable etc. may be reported by JVM as unknown. Such roots will be shown in UI as "Held by JVM". To avoid this, please upgrade to newer (and better!) Java versions if possible.