Chapter 4. Configuration options for JDK Flight Recorder

You can configure JDK Flight Recorder (JFR) to capture various sets of events using the command line or diagnostic commands.

4.1. Configure JDK Flight Recorder using the command line

You can configure JDK Flight Recorder (JFR) from the command line using the following options:

4.1.1. Start JFR

Use -XX:StartFlightRecording option to start a JFR recording for the Java application. For example:

java -XX:StartFlightRecording=delay=5s,disk=false,dumponexit=true,duration=60s,filename=myrecording.jfr <<YOUR_JAVA_APPLICATION>>

You can set the following parameter=value entries when starting a JFR recording:

delay=time

Use this parameter to specify 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 is no delay, and this parameter is set to 0.

disk={true|false}

Use this parameter to specify whether to write data to disk while recording. By default, this parameter is true.

dumponexit={true|false}

Use this parameter to specify if the running recording is dumped when the JVM shuts down. If the parameter is enabled and a file name is not set, the recording is written to a file in the directory where the recording progress has started. The file name is a system-generated name that contains the process ID, recording ID, and current timestamp. For example, hotspot-pid-47496-id-1-2018_01_25_19_10_41.jfr. By default, this parameter is false.

duration=time

Use this parameter to specify 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, if you specify duration as 5h, it indicates 5 hours. By default, this parameter is set to 0, which means there is no limit set on the recording duration.

filename=path

Use this parameter to specify the path and name of the recording file. The recording is written to this file when stopped. For example:

· recording.jfr

· /home/user/recordings/recording.jfr

name=identifier

Use this parameter to specify both the name and the identifier of a recording.

maxage=time

Use this parameter to specify the maximum number of days the recording should be available on the disk. 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, when you specify 30s, it indicates 30 seconds. By default, this parameter is set to 0, which means there is no limit set.

maxsize=size

Use this parameter to specify the maximum size 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 isn’t limited, and this parameter is set to 0.

path-to-gc-roots={true|false}

Use this parameter to specify whether to collect the path to garbage collection (GC) roots at the end of a recording. By default, this parameter is set to false.

The path to GC roots is useful for finding memory leaks. For Red Hat build of OpenJDK 17, you can enable the OldObjectSample event which is a more efficient alternative than using heap dumps. You can also use the OldObjectSample event in production. Collecting memory leak information is time-consuming and incurs extra overhead. You should enable this parameter only when you start recording an application that you suspect has memory leaks. If the JFR profile parameter is set to profile, you can trace the stack from where the object is leaking. It is included in the information collected.

settings=path

Use this parameter to specify the path and name of the event settings file (of type JFC). By default, the default.jfc file is used, which is located in JAVA_HOME/lib/jfr. This default settings file collects a predefined set of information with low overhead, so it has minimal impact on performance and can be used with recordings that run continuously. The second settings file is also provided, profile.jfc, which provides more data than the default configuration, but can have more overhead and impact performance. Use this configuration for short periods of time when more information is needed.

Note

You can specify values for multiple parameters by separating them with a comma. For example, -XX:StartFlightRecording=disk=false,name=example-recording.

4.1.2. Control behavior of JFR

Use -XX:FlightRecorderOptions option to sets the parameters that control the behavior of JFR. For example:

java -XX:FlightRecorderOptions=duration=60s,filename=myrecording.jfr -XX:FlightRecorderOptions=stackdepth=128,maxchunksize=2M <<YOUR_JAVA_APPLICATION>>

You can set the following parameter=value entries to control the behavior of JFR:

globalbuffersize=size: Use this parameter to specify the total amount of primary memory used for data retention. The default value is based on the value specified for memorysize. You can change the memorysize parameter to alter the size of global buffers.
maxchunksize=size: Use this parameter to specify the maximum size 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 size allowed is 1 MB.
memorysize=size: Use this parameter to determine how much buffer memory should be used. The parameter 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=number: Use this parameter to specify the number of global buffers used. The default value is based on the size specified in the memorysize parameter. You can change the memorysize parameter to alter the number of global buffers.
old-object-queue-size=number-of-objects: Use this parameter to track the maximum number of old objects. By default, the number of objects is set to 256.
repository=path: Use this parameter to specify the repository for temporary disk storage. By default, it uses system temporary directory.
retransform={true|false}: Use this parameter to specify if event classes should be retransformed using JVMTI. If set to false, instrumentation is added to loaded event classes. By default, this parameter is set to true for enabling class retransformation.
samplethreads={true|false}: Use this parameter to specify whether thread sampling is enabled. Thread sampling only occurs when the sampling event is enabled and this parameter is set to true. By default, this parameter is set to true.
stackdepth=depth: Use this parameter to set the stack depth for stack traces. By default, the stack depth is set to 64 method calls. You can set the maximum stack depth to 2048. Values greater than 64 could create significant overhead and reduce performance.
threadbuffersize=size: Use this parameter to specify the local buffer size for a thread. 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.

Note

You can specify values for multiple parameters by separating them with a comma.

4.2. Configuring JDK Flight Recorder using diagnostic command (JCMD)

You can configure JDK Flight Recorder (JFR) using Java diagnostic command. The simplest way to execute a diagnostic command is to use the jcmd tool which is located in the Java installation directory. To use a command, you have to pass the process identifier of the JVM or the name of the main class, and the actual command as arguments to jcmd. You can retrieve the JVM or the name of the main class by running jcmd without arguments or by using jps. The jps(Java Process Status) tool lists JVMs on a target system to which it has access permissions.

To see a list of all running Java processes, use the jcmd command without any arguments. To see a complete list of commands available for a running Java application, specify help as the diagnostic command after the process identifier or the name of the main class.

Use the following diagnostic commands for JFR:

4.2.1. Start JFR

Use JFR.start diagnostic command to start a flight recording. For example:

jcmd <PID> JFR.start delay=10s duration=10m filename=recording.jfr

Table 4.1. The following table lists the parameters you can use with this command:
Parameter	Description	Data type	Default value
name	Name of the recording	String	-
settings	Server-side template	String	-
duration	Duration of recording	Time	0s
filename	Resulting recording file name	String	-
maxage	Maximum age of buffer data	Time	0s
maxsize	Maximum size of buffers in bytes	Long	0
dumponexit	Dump running recording when JVM shuts down	Boolean	-
path-to-gc-roots	Collect path to garbage collector roots	Boolean	False

4.2.2. Stop JFR

Use JFR.stop diagnostic command to stop running flight recordings. For example:

jcmd <PID> JFR.stop name=output_file

Table 4.2. The following table lists the parameters you can use with this command.
Parameter	Description	Data type	Default value
name	Name of the recording	String	-
filename	Copy recording data to the file	String	-

4.2.3. Check JFR

Use JFR.check command to show information about the recordings which are in progress. For example:

jcmd <PID> JFR.check

Table 4.3. The following table lists the parameters you can use with this command.
Parameter	Description	Data type	Default value
name	Name of the recording	String	-
filename	Copy recording data to the file	String	-
maxage	Maximum duration to dump file	Time	0s
maxsize	Maximum amount of bytes to dump	Long	0
begin	Starting time to dump data	String	-
end	Ending time to dump data	String	-
path-to-gc-roots	Collect path to garbage collector roots	Boolean	false

4.2.4. Dump JFR

Use JFR.dump diagnostic command to copy the content of a flight recording to a file. For example:

jcmd <PID> JFR.dump name=output_file filename=output.jfr

Table 4.4. The following table lists the parameters you can use with this command.
Parameter	Description	Data type	Default value
name	Name of the recording	String	-
filename	Copy recording data to the file	String	-
maxage	Maximum duration to dump file	Time	0s
maxsize	Maximum amount of bytes to dump	Long	0
begin	Starting time to dump data	String	-
end	Ending time to dump data	String	-
path-to-gc-roots	Collect path to garbage collector roots	Boolean	false

4.2.5. Configure JFR

Use JFR.configure diagnostic command to configure the flight recordings. For example:

jcmd <PID> JFR.configure repositorypath=/home/jfr/recordings

Table 4.5. The following table lists the parameters you can use with this command.
Parameter	Description	Data type	Default value
repositorypath	Path to repository	String	-
dumppath	Path to dump	String	-
stackdepth	Stack depth	Jlong	64
globalbuffercount	Number of global buffers	Jlong	32
globalbuffersize	Size of a global buffer	Jlong	524288
thread_buffer_size	Size of a thread buffer	Jlong	8192
memorysize	Overall memory size	Jlong	16777216
maxchunksize	Size of an individual disk chunk	Jlong	12582912
Samplethreads	Activate thread sampling	Boolean	true

Revised on 2024-05-03 15:34:54 UTC

Chapter 4. Configuration options for JDK Flight Recorder

4.1. Configure JDK Flight Recorder using the command line

4.1.1. Start JFR

4.1.2. Control behavior of JFR

4.2. Configuring JDK Flight Recorder using diagnostic command (JCMD)

4.2.1. Start JFR

4.2.2. Stop JFR

4.2.3. Check JFR

4.2.4. Dump JFR

4.2.5. Configure JFR

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

Making open source more inclusive

About Red Hat

Red Hat legal and privacy links

Red Hat legal and privacy links