Specifying a custom Event Settings file for Java Flight Recorder

When you are using Java Flight Recorder (JFR), the JFR will use an event settings file to check which event types to record.

By default in JFR, there are two settings, "default" and "profile". The default setting is recommended for Continuous Recordings as it has very low overhead (typically less than 1% overhead). The profile setting has more events and useful when profiling the application.

As mentioned in my previous blog post regarding Java Flight Recorder Continuous Recordings, we use following arguments to do a Continuous Recording.

-XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:FlightRecorderOptions=defaultrecording=true,disk=true,repository=./tmp,dumponexit=true,dumponexitpath=./


Note: According to the Oracle documentation on "java" command, we should be able to specify "settings" parameter to the -XX:FlightRecorderOptions. However, the settings parameter has no effect when used with the -XX:FlightRecorderOptions and the default settings will be used. This is a known bug in JFR.

In JFR, the "settings" parameter specifies the path and name of the event settings file, which is of type JFC and it has the ".jfc" extension. By default, the "default.jfc" file is used and it's located in JAVA_HOME/jre/lib/jfr directory.

Most of the time, the "default" and "profile" settings are enough. However you might have seen that when analyzing a JFR dump, some tabs in Java Mission Control will tell that the particular event type is not enabled in that recording.

For example, the "Object Count" event is not enabled by default in "default" or "profile" settings. Therefore we cannot see "Object Statistics" in the Memory Group Tab.

We need to enable such events from a settings file.

Creating a custom Event Settings file

The recommended way to create a custom settings event file is to use Java Mission Control. Once you start the Java Mission Control (JMC), open "Flight Recorder Template Manager" from the Window menu.

Screenshot 01: Flight Recorder Template Manager

Let's import the existing profile.jfc to "Flight Recorder Template Manager". Click on "Import Files..." and select JAVA_HOME/jre/lib/jfr/profile.jfc. (Eg: /usr/lib/jvm/jdk1.8.0_74/jre/lib/jfr/profile.jfc)

Now let's duplicate that by selecting the "Profiling" template and clicking on "Duplicate".

Screenshot 02: The Duplicate Profiling Template

The new template is now named as "Profiling (1)". Let's edit it by clicking on "Edit".

Now let's change the "Name", "Description" and other settings that we need to record.

Screenshot 03: Template Options

I selected "Heap Statistics" and "Class Loading". I recommend you to open the default *.jfc files and go through the file to understand the events available in JFR. For example, from the file I can see that we need to enable "Heap Statistics" to enable the "Object Count" event.

Note: When we select the options shown in Screenshot 03, it will only update the "Control Elements". You can see these control elements when you open a JFC file in JAVA_HOME/jre/lib/jfr/. These control elements will change the real state of the settings. When you click on "Advanced", it will display the "Template Event Details". It will also show the warning: " If you click OK, this template will always be opened in advanced mode and the simple controls will be lost." Click on "OK" only if you want get rid of control elements from the settings file. 

Screenshot 04: Template Event Details

Click on "Cancel" and click on "OK" to save the "Template Options".

Let's export this file to a directory using "Export File..." button.

Specifying the Event Settings file for JFR

After creating the settings file, we can directly specify the settings file name in "settings" parameter. Since we cannot specify the "settings" parameter with -XX:FlightRecorderOptions, we will start a new recording from the "jcmd" command.

For example, add following parameters to the Java program.


-XX:+UnlockCommercialFeatures -XX:+FlightRecorder


Then we can start a recording as follows.

$ jcmd `cat wso2carbon.pid` JFR.start settings=/home/isuru/performance/jfr-settings/Heap.jfc  
30849:
Started recording 1. No limit (duration/maxsize/maxage) in use.

Use JFR.dump recording=1 filename=FILEPATH to copy recording data to file.

Note:

1. You can also use settings parameter with -XX:StartFlightRecording option.
2. I used a WSO2 server to test JFR recording and the Process ID is available in CARBON_HOME/wso2carbon.pid file.
3. If you save the JFC file in JAVA_HOME/jre/lib/jfr directory, you can just use the filename in settings parameter. For eg: "settings=Heap"

Now we can get a JFR dump from jcmd command.

$ jcmd `cat wso2carbon.pid` JFR.dump recording=1 filename=heap.jfr
30849:
Dumped recording 1, 58.4 MB written to:

/home/isuru/temp/metrics-test/wso2am-1.10.0/heap.jfr

When you open the JFR, you will be able to see "Object Statistics" in the Memory Group Tab.