Java Flight Recorder

Java Flight Recorder is a profiling tool for Java which is included in the Java Virtual Machine (since JDK version 7u40 or newer). The overhead of the tool is very small when we use the default profiling setting (the performance impact is below 1%). This makes it attractive for profiling applications even in heavily loaded production environments.

Start a Recording

There are two ways to start the Java Flight Recorder for an application: i) through java options in the command line at the time the application is started, or ii) through the diagnostic command tool (jcmd) for an application that is already running.

Start JFR at Application Start

To enable JFR when the application starts, the following JVM options have to be provided:

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:StartFlightRecording=duration=600s,filename=events.jfr MyApplication

Java Flight Recorder is a commercial feature, available only in the commercial packages based on Java Platform, Standard Edition (Oracle Java SE Advanced and Oracle Java SE Suite). For this reason we have to enable the commercial features with -XX:+UnlockCommercialFeatures. The option, -XX:+FlightRecorder, enables the flight recorder, while –XX:StartFlightRecording=duration=600s,filename=events.jfr, starts the recording which will run for 600 seconds. The collected profile is saved into events.jfr file located in the working directory of the application. If the duration is not specified, a default value of 0s is used which corresponds to unlimited.

Start JFR by Diagnostic Command

The diagnostic command allows us to start JFR for a Java application that is already running. The diagnostic command (jcmd) is part of the JDK and can be found at the following location: ${JAVA_HOME}/bin/jcmd. Executing jcmd command without any arguments will list all the running java applications. The diagnostic command has the following format:

jcmd PID <command> [parameters]

The following commands are available:

1. JFR.start – starts a recording
2. JFR.check – checks the status of all recording for the specified process
3. JFR.stop – stops a recording with the given identification number
4. JFR.dump – dumps the data collected by the recording with the given identification number

Each command has a number of one or more parameters. For instance, the following parameters can be provided when starting a recording:

• duration – the duration for which the recording is run (default value is 0s, which is unlimited)
• filename – the file where the recording is saved
• maxsize – a recording can be set to have a max size. Units used: k or K-for kilobytes, m or M-for megabytes, g or G-for gigabytes
• maxage – a recording can be set to have a max age. Units used: s-for seconds, m-for minutes, h-for hours, and d-for days.
• delay – a recording can be started with a delay. This is useful when the user wants to wait a certain period until the application reaches a steady state.
• compress – setting the value to true will compress the recording into a zip archive.

Important note: Executing the JFR commands is only possible for Java applications that have been started with the Java Flight Recorder setting enabled: i.e., -XX:+UnlockCommercialFeatures -XX:+FlightRecorder

Visualizing Recordings

For visualizing the profiles we can use the JMC tool, that is also part of the JDK and can be found at the following location ${JAVA_HOME}/bin/jmc.

References

1. Java Platform, Standard Edition Java Flight Recorder Runtime Guide
2. Running Java Flight Recorder
3. Java Platform, Standard Edition Java Mission Control User’s Guide