The Java Mission Control and the Java Flight Recorder allow us to capture run-time information from our Java applications without much overhead and aggregate profiling information.

I have written down the commands that I’m using the most when profiling a Java application with this tool chain in the following article.

java mission control reports 1024x629
Figure 1. Java Mission Control - Report

Running Java Mission Control (JMC)

We may start the JMC user interface shown above using the jmc command that is shipped with Oracle’s JRockit or Java (since Java 7 update 40).

Java Mission Control allows us to connect to a running Java application via JMX and capture runtime information from the Flight Recorder (JFR), executing commands via JMX or displaying reports from JFR sessions.

Activating Commercial Features and the Java Flight Recorder

At the moment of writing this article, we need to activate the commercial features to be able to use the Flight Recorder (as using it for production requires a commercial license) but Oracle recently published this announcement to contribute the Flight Recorder to the OpenJDK so that might not be necessary any more in the future.

Activation with Application Start

If we know that we might want to use the JFR later, we may start our application with commercial features unlocked and JFR activated adding the following JVM parameters:

-XX:+UnlockCommercialFeatures -XX:+FlightRecorder

For example when running the Vert.x application from my tutorial here that I’ll be using as sample application for the rest of this tutorial we would start the application like this (using its fat-jar):

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -jar vertx-websocket-chat-1.0.0-fat.jar

Activation for Running Applications

Using jcmd allows us to activate those features for a running application. The first step is to determine the application’s Java-Process-Id using jps or jcmd:

$ jps -l
18040 sun.tools.jps.Jps
17839 vertx-websocket-chat-1.0.0-fat.jar

$ jcmd
17839 vertx-websocket-chat-1.0.0-fat.jar
18063 sun.tools.jcmd.JCmd

So now we now, that our application’s process id is 17839.

We can now check if our application has commercial features etc. activated (it has not):

$ jcmd 17839 VM.check_commercial_features
17839:
Commercial Features are locked.

We’re using jcmd again to unlock those features:

$ jcmd 17839 VM.unlock_commercial_features
17839:
Commercial Features now unlocked.

And we’re checking that they are unlocked now and we’re ready to use the Flight Recorder:

$ jcmd 17839 VM.check_commercial_features
17839:
Commercial Features are unlocked.
Status of individual features:
Java Flight Recorder has not been used.
Resource Management is disabled.
Current Memory Restriction: None (0)

More detailed information is available in Oracle’s documentation.

Capturing Information with the Flight Recorder

Now that the Flight Recorder is enabled for our application we may start capturing data.

One way is to use the JMC GUI, connect to the process, configure selection details and start recording, the other way is to trigger capturing on the command line.

Start and Capture an Application

If we want to start an application, record information with the Flight Recorder and dump the captured information to a file we may use jcmd like this:

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:StartFlightRecording=duration=60s,filename=vertx-1minute-recording.jfr -jar vertx-websocket-chat-1.0.0-fat.jar

After one minute we may load the capture from the file named vertx-1minute-recording.jfr into the JMC GUI.

Capture a Running Application

If we want to capture information from a running application we may use jcmd like this:

$ jcmd 17839 JFR.start duration=60s filename=vertx-1minute-live-recording.jfr
18792:
Started recording 1. The result will be written to:

/data/project/vertx-websocket-chat/target/vertx-1minute-live-recording.jfr

Using JMC and Triggers to Start Flight Recorder

Connecting to the MBean server we may create triggers that may write log-files, send an e-mail or start capturing information with the flight recorder.

A trigger may be a reached treshold in CPU usage, memory usage, deadlocked threads and so on.

mbean server add trigger 1024x629
Figure 2. Adding triggers in JMC
start flight recorder by trigger 1024x629
Figure 3. Trigger emitted flight recorder start

JMX Remote Configuration

Warning: Authentication is disabled for the following example:

java -Dcom.sun.management.jmxremote.port=7091 -Dcom.sun.management.jmxremote.authenticate=false -Dcom.sun.management.jmxremote.ssl=false -jar vertx-websocket-chat-1.0.0-fat.jar

Reading Recommendation: Marcus Hirt

For the latest information about the progress of the JMC and JFR, I highly recommend reading Marcus Hirt’s blog covering a lot of interesting topics e.g. the Java Flight Recorder in Java JDK 9.

Resources

Troubleshooting

  • JMC does not find remote Java process: Enable JMX autodiscovery using the following parameters:

    -Dcom.sun.management.jmxremote.autodiscovery=true -Dcom.sun.management.jdp.name=vmname (optional)

Legal Note: “Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.”

Article Updates

  • 2017-10-17: JMX remote configuration examples and trigger based flight recorder examples added.