Menu Close

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 OpenJDK 11, 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:

ParameterDescriptionData typeDefault 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.

ParameterDescriptionData typeDefault 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.

ParameterDescriptionData typeDefault 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.

ParameterDescriptionData typeDefault 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.

ParameterDescriptionData typeDefault 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 2022-07-15 14:48:54 UTC