How to use Oracle JDK Java Flight Recorder

Solution Verified - Updated -

Environment

  • Red Hat JBoss Enterprise Application Platform (EAP)
    • 6.x
    • 5.2
  • Linux
  • Windows
  • Oracle JDK
    • 1.7.0_40 and up

Issue

  • How to use Oracle JDK Java Flight Recorder ?
  • Heap dump can't be provided because it contains sensitive information.
  • Heap dump from a production system can't be provided due to application performance impact.
  • Using instructions in https://access.redhat.com/solutions/700283, able to connect to a remote EAP6 instance using Java Mission Control (Oracle JDK 7u 72) . However, when tried to invoke JMC flight recorder, getting following message:
Commercial features are not enabled. To enable this, you need to use Java 7u4 or later JVM started with  -XX:+UnlockCommercialFeatures (To enable Flight Recorder, also add -XX:+FlightRecorder)

Resolution

To use Oracle JDK's Java Flight Recorder (JFR) it is needed to run JBoss EAP with the following options:

-XX:+UnlockCommercialFeatures -XX:+FlightRecorder

These can be used with JAVA_OPTS on the shell, or editing

  • EAP 6.x
    • Standalone mode - $JBOSS_HOME/bin/standalone.conf on Linux or $JBOSS_HOME/bin/standalone.conf.bat on Windows.
    • Domain mode - $JBOSS_HOME/domain/configuration/domain.xml or $JBOSS_HOME/domain/configuration/host*.xml depending on where the JVM parameters are set
  • EAP 5.2+ $JBOSS_HOME/bin/run.conf - (Java 7 only supported from EAP 5.2.0)

Once JBoss starts with both options, jcmd is the application needed to start, check, dump and stop JFR.

  • $JAVA_HOME/bin/jcmd $JBOSS_PID JFR.start -> Starts JFR recording. It returns the recording number, which is used to dump the results to disk
  • $JAVA_HOME/bin/jcmd $JBOSS_PID JFR.check -> Lists the number of recordings running
  • $JAVA_HOME/bin/jcmd $JBOSS_PID JFR.dump recording=<recording_number> filename=<path/file> -> Dumps the JFR recording to disk
  • $JAVA_HOME/bin/jcmd $JBOSS_PID JFR.stop recording=<recording_number> -> Stops the specified JFR recording. This should be done after dumping and not prior.

$JAVA_HOME/bin/jcmd $JBOSS_PID help and any of the commands above can be used to list the available options for each command.

To limit the duration of the recording, to for 4 hours for example, use run:

$JAVA_HOME/bin/jcmd $JBOSS_PID JFR.start duration=4h

A JFR recording should occur when the system starts displaying the problematic behaviour on a production environment. On a development or testing environment, recording can start as soon as JBoss comes up and stop after the testing is done.

Note that JFR should be running as the same user the EAP service is running under. For instance, running EAP as the LOCAL SYSTEM account and JFR as the currently logged in user will result in an "Insufficient Privileges" error. You can use the PsExec Tool from Microsoft to escalate to the proper user.

More information can be found here and Java Components page

This solution is part of Red Hat’s fast-track publication program, providing a huge library of solutions that Red Hat engineers have created while supporting our customers. To give you the knowledge you need the instant it becomes available, these articles may be presented in a raw and unedited form.

2 Comments

This is a good intro to jcmd, assuming the process is running under your id.

If it is a service, jcmd will not work in any way. Could someone address how to use jcmd with a service?

Try using psexec. To take a heap dump, the following works:

psexec -s jcmd $JBOSS_PID GC.heap_dump -all=true c:\dumps\dump.hprof