Configuring the JDK Flight Recorder

The JDK Flight Recorder comes with a default set of heuristics and settings. These default settings might work for trivial cases, but in most production settings, users will need to configure JFR to suit their specific needs better. There are four distinct levels of configuring JFR; recording options, configuration settings, event settings, and flight recorder options. Each will be covered in this section.

Recording Options

Recording options govern the overall behavior of JFR, covering settings like how long data will be retained, which configurations will be used, and more. Recording options are provided at JFR initialization; -XX:StartFlightRecording or JFR.start, or with JFR.config.

Note: -XX:StartFlightRecording, and JFR.start and JFR.config all take the same options, however when using -XX:StartFlightRecording, each option is delimited by a comma (,) while with JFR.start and JFR.config use a space ( ). The below examples result in the same configuration:

java -XX:StartFlightRecording:filename=recording.jfr,settings=profile.jfc

JFR.start filename=recording.jfr settings=profile.jfc

• delay=time: Specifies the delay between the Java application launch time and the start of the recording. Append s to specify the time in seconds, m for minutes, h for hours, or d for days (for example, specifying 10m means 10 minutes). By default, there's no delay, and this parameter is set to 0.
• disk={[true]|false}: Specifies whether to write data to disk while recording. By default, this parameter is enabled.
• dumponexit={true|[false]}: Specifies if the running recording is dumped when the JVM shuts down. If enabled and a filename is not entered, the recording is written to a file in the directory where the process was started. The file name is a system-generated name that contains the process ID, recording ID, and current timestamp, similar to hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By default, this parameter is disabled.
• duration=time: Specifies the duration of the recording. Append s to specify the time in seconds, m for minutes, h for hours, or d for days (for example, specifying 5h means 5 hours). By default, the duration isn't limited, and this parameter is set to 0.
• filename=path: Specifies the path and name of the file to which the recording is written when the recording is stopped, for example:

        recording.jfr
        /home/user/recordings/recording.jfr
        c:\recordings\recording.jfr

• name=identifier: Takes both the name and the identifier of a recording.

• maxage=time: Specifies the maximum age of disk data to keep for the recording. This parameter is valid only when the disk parameter is set to true. Append s to specify the time in seconds, m for minutes, h for hours, or d for days (for example, specifying 30s means 30 seconds). By default, the maximum age isn't limited, and this parameter is set to 0s.

• maxsize=size: Specifies the maximum size (in bytes) of disk data to keep for the recording. This parameter is valid only when the disk parameter is set to true. The value must not be less than the value for the maxchunksize parameter set with -XX:FlightRecorderOptions. Append m or M to specify the size in megabytes, or g or G to specify the size in gigabytes. By default, the maximum size of disk data is limited to 250 MB.

• path-to-gc-roots={true|false}: Specifies whether to collect the path to garbage collection (GC) roots at the end of a recording. By default, this parameter is disabled.

  • The path to GC roots is useful for finding memory leaks, but collecting it is time-consuming. Enable this option only when you start a recording for an application that you suspect has a memory leak. If the settings parameter is set to profile, the stack trace from where the potential leaking object was allocated is included in the information collected.

• settings=path: Specifies the path and name of the event settings file (of type JFC).

  You can specify values for multiple parameters by separating them with a comma. Event settings and .jfc options can be specified using the following syntax:

  • option=value: Specifies the option value to modify. To list available options, use the JAVA_HOME/bin/jfr tool. event-setting=value
  • <event-name>#<setting-name>=<value>: Specifies the event setting value to modify. To add a new event setting, prefix the event name with +.

Configuration Settings

Configuration settings are defined in JFR configuration files (.jfc) and are supplied to JFR through the settings option. They contain the event settings as well as controls that JDK Mission Control will use. JFR comes with two pre-defined settings files; default.jfc and profile.jfc, which are located in JAVA_HOME/lib/jfr.

Note: As of JDK 19, it's strongly encouraged to use the jfr configure utility for creating settings files.

Event Options

Primarily defined in configuration files, event options govern how JFR collects events. Since JDK 17, these values can also be supplied through -XX:StartFlightRecording, JFR.start, and JFR.config. Event option settings provided through command-line override settings provided in .jfc files, and both override settings provided by annotations in an event's class.

• enabled: Boolean, governs if JFR will collect an event. The default is true.
• period: Duration, governs the minimum length of time JFR will wait before recording another instance of this event. The default is 0. Provide ns for nanoseconds, ms for milliseconds, s for seconds, m for minutes, h for hours.
• threshold: Duration, governs the minimum length of time it takes this event to execute before JFR will record the event. The default is 0. Provide ns for nanoseconds, ms for milliseconds, s for seconds, m for minutes, h for hours.
• stackTrace: Boolean, governs if JFR will record the stackTrace associated with the event. The default is true.

Flight Recorder Options

These set of configurations, supplied through the -XX:FlightRecorderOptions JVM argument, generally govern how JFR handles the flow of data from the recording of events to storing them in memory or on disk. Often the default values will be enough for most users, but a user might need to change the defaults to suit their performance goals better.

Each option is delimited with a comma (,) like in this example:

java -XX:FlightRecorderOptions:maxchunksize=1M,numglobalbuffers=5

• globalbuffersize=size: Specifies the total amount of primary memory used for data retention. The default value is based on the value specified for memorysize. Change the memorysize parameter to alter the size of global buffers.
• maxchunksize=size: Specifies the maximum size (in bytes) of the data chunks in a recording. Append m or M to specify the size in megabytes (MB), or g or G to specify the size in gigabytes (GB). By default, the maximum size of data chunks is set to 12 MB. The minimum allowed is 1 MB.
• memorysize=size: Determines how much buffer memory should be used, and sets the globalbuffersize and numglobalbuffers parameters based on the size specified. Append m or M to specify the size in megabytes (MB), or g or G to specify the size in gigabytes (GB). By default, the memory size is set to 10 MB.
• numglobalbuffers: Specifies the number of global buffers used. The default value is based on the memory size specified. Change the memorysize parameter to alter the number of global buffers.
• old-object-queue-size=number-of-objects: Maximum number of old objects to track. By default, the number of objects is set to 256.
• repository=path: Specifies the repository (a directory) for temporary disk storage. By default, the system's temporary directory is used.
• retransform={[true]|false}: Specifies whether event classes should be retransformed using JVMTI (Java Virtual Machine Tool Interface). If false, instrumentation is added when event classes are loaded. By default, this parameter is enabled.
• stackdepth=depth: Stack depth for stack traces. By default, the depth is set to 64 method calls. The maximum is 2048. Values greater than 64 could create significant overhead and reduce performance.
• threadbuffersize=size: Specifies the per-thread local buffer size (in bytes). By default, the local buffer size is set to 8 kilobytes, with a minimum value of 4 kilobytes. Overriding this parameter could reduce performance and is not recommended.