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
maxchunksizeparameter 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
OldObjectSampleevent which is a more efficient alternative than using heap dumps. You can also use theOldObjectSampleevent 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.
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 thememorysizeparameter 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
globalbuffersizeandnumglobalbuffersparameters 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
memorysizeparameter. You can change thememorysizeparameter 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 totruefor 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 totrue. - 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.
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
| 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
| 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
| 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
| 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
| 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
