What is JVM startup parameter: -XX:StartFlightRecording?

Usage:

 This flag allows to start Java Flight Recording (JFR) with options. The syntax of the parameter is: -XX:StartFlightRecording=option=value, where option can be one of these following options: “delay, disk, dumponexit, duration, filename, name, maxage, maxsize, path-to-gc-roots or settings”.

Since:

Starting from JDK 11.

Examples:

This will instruct JVM to start a JFR recording with a delay for 10 minutes:

-XX:StartFlightRecording=delay=10m.

Description:

Java Flight Recorder is referred to as JFR, is supported since JDK version 11. It is a low-overhead data collection framework that can be used to analyze Java application and JVM health and performance issues in production environments. JFR logs runtime events from the application, as well as the JVM and OS. The recorded results are stored in a separate file that can be used by development engineers to analyze bugs and performance issues.

JFR expands on JEP:167's Event-based JVM Tracing. JEP167 simply outputs events to stdout, while JFR provides higher-performance binary-based event output and it has two main aspects: events & dataflow.

The JDK introduced the parameter “StartFlightRecording” for enabling JFR with the following options: “delay, disk, dumponexit, duration, filename, name, maxage, maxsize, path-to-gc-roots or settings”. Let's briefly discuss them:

• delay=value: It allows you to add a time delay of the start of the recording. By default, it’s 0. For seconds, minutes, hours or days, you can append to the value the character ‘s’, ‘m’, ‘h’ or ‘d’ respectively.
• disk={true|false}: It allows you to control if the data will be writing on the disk or not. By default, this parameter is enabled.
• dumponexit={true|false}: It dumps the recording in a file when the JVM shuts down. If enabled and the parameter “filename” is not specified, then it will dump the file to the working directory of the process. By default, this parameter is disabled.
• duration=time: The duration of the recording. By default, the duration is not limited and the parameter is 0. (You can also specify the time with seconds ‘s’, minutes ‘m’ …
• filename=path: The full path where the recording will be writer.
• name=identifier: Allows you to choose a name and the identifier of the recording.
• maxage=time: Specify the maximum time to keep the recording. This parameter works only when the option “disk” is enabled. By default, there is no time limit for the recording and the default value is 0.
• maxsize=size: Specify the maximum size in bytes of disk for records. This parameter works only when the option “disk” is enabled. By default, there is no size limit for the recording and the default value is 0.
• path-to-gc-roots={true|false): It allows you to specify if you want to collect the path to Garbage Collection (GC) roots at the end of the recording. By default, this option is disabled.
• settings=path: Specify the full path of the event settings file of type JFC. By default, the “default.jfc” is used located in “JRE_HOME/lib/jfr”.

Example of using JFR:

Let’s run this code snippet:

public class JFRTest {

    public static void main(String[] args) {

        int counter = 0;

        Map<Integer, Integer> counters = new HashMap<>();

        for(int i=0; i < 100; i *= i) {

            counters.put(counter++, counter++ * 1000);

        }

    }

}

First of all, we need to compile this class with the following command:

javac -d out -sourcepath src/main src/main/com/test/JFRTest.java

The file JFRTest.java is located in package com.test

PS: if you are using Windows OS, then replace “/” with “\”.

Afterwards, we will run our application with the command:

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:StartFlightRecording=duration=200s,filename=flight.jfr -cp ./out/ com.test.JFRTest

PS: If your JDK doesn’t recognize the parameter “UnlockCommercialFeatures” then you can remove it.

Finally, we have a recording and the last part is to analyse it. There are some tools to analyse the recording such as JDK Mission Control (JMC)

Using this tool, we can analyse the memory, threads, GC, … and as you can see, in our application we are using too much memory.

Default Value:

By default, this flag is disabled.

Arguments related:

UnlockCommercialFeatures

Related Posts:

• About Java Flight Recorder
• Monitoring Java Applications with Flight Recorder
• JDK Mission Control
• Java Oracle