Getting Started with the JDK Flight Recorder

This section will cover the basics of starting a JFR recording and extracting data from a recording. In most cases users will want to provide configuration when starting JFR, but we will cover configuring JFR in the next section.

Starting a JFR Recording

JFR can be started at JVM startup, as well as enabled on an already running JVM. In most cases, initializing JFR at startup is the best option to provide the most complete picture of a JVM; however, enabling JFR on a running JVM can be helpful if a JVM starts encountering and you want to collect data on it before shutting it down.

Enabling JFR on Startup

To enable JFR on startup, include the VM argument -XX:StartFlightRecording to your java command like in this example:

java -XX:StartFlightRecording MyMainClass

This is only a very basic way of running JFR and unlikely to fulfill the needs of most JFR users. -XX:StartFlightRecording is able to take several configuration arguments. Which, as mentioned, will be covered in the next section.

Enabling JFR on a Running JVM with JCMD

JFR can also be enabled on a running JVM using jcmd. The first step will be getting the process id (pid) of the Java process you want to enable JFR on. The Java command line utility jps can be used for this like in this example:

$ jps
75681 Jps
27017 ApplicationMain

If you wanted to enable JFR on the java process ApplicationMain, then you'd run:

$ jcmd 27017 JFR.start

Like -XX:StartFlightRecording, JFR.start can also take configuration arguments.

Retrieving Data from JFR

With JFR running on a Java process, naturally, there would be an interest in examining the data being collected. There are several ways of doing this, in this section we will explore extracting data from JFR using jcmd.

Extracting JFR Data with JCMD

jcmd can be used to manually extract data from JFR, referred to as data dumps. You can execute a dump with the following command:

jcmd <pid> JFR.dump

Additionally, JFR.dump can take the below arguments, all of which are optional:

• begin: Specify the time from which recording data will be included in the dump file. The format is specified as local time. (STRING, no default value)

• end: Specify the time to which recording data will be included in the dump file. The format is specified as local time. (STRING, no default value)

  • Note: For both begin and end, the time must be in a format that can be read by java.time.LocalTime::parse(STRING), java.time.LocalDateTime::parse(STRING) or java.time.Instant::parse(STRING). For example, "13:20:15", "2020-03-17T09:00:00" or "2020-03-17T09:00:00Z".

  • Note: begin and end times correspond to the timestamps found within the recorded information in the flight recording data.

  • Another option is to use a time relative to the current time that is specified by a negative integer followed by "s", "m" or "h". For example, "-12h", "-15m" or "-30s"

• filename: Name of the file to which the flight recording data is dumped. If no filename is given, a filename is generated from the PID and the current date. The filename may also be a directory in which case, the filename is generated from the PID and the current date in the specified directory. (STRING, no default value)

• maxage: Length of time for dumping the flight recording data to a file. (INTEGER followed by 's' for seconds 'm' for minutes or 'h' for hours, no default value)

• maxsize: Maximum size for the amount of data to dump from a flight recording in bytes if one of the following suffixes is not used: 'm' or 'M' for megabytes OR 'g' or 'G' for gigabytes. (STRING, no default value)

• name: (Optional) Name of the recording. If no name is given, data from all recordings is dumped. (STRING, no default value)

• path-to-gc-root: Flag for saving the path to garbage collection (GC) roots at the time the recording data is dumped. The path information is useful for finding memory leaks but collecting it can cause the application to pause for a short period of time. Turn on this flag only when you have an application that you suspect has a memory leak. (BOOLEAN, false)

Admin Actions when Running JFR

In inclusion to the the jcmd actions; JFR.start and JFR.dump already covered, jcmd provides three other adminstrator actions.

• JFR.configure : Used updating the configuration of JFR.
• JFR.check : Provides basic diagnostic information about a JVM running JFR
• JFR.stop name=[recording name] : Used to stop a JFR recording. name is a required argument.