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: 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: 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: 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: 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: 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: 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: 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

Commands:
java -XX:StartFlightRecording=delay=5s,disk=false,dumponexit=true,duration=60s,filename=myrecording.jfr <<YOUR_JAVA_APPLICATION>>
java -XX:FlightRecorderOptions=duration=60s,filename=myrecording.jfr -XX:FlightRecorderOptions=stackdepth=128,maxchunksize=2M <<YOUR_JAVA_APPLICATION>>
jcmd <PID> JFR.start delay=10s duration=10m filename=recording.jfr
jcmd <PID> JFR.stop name=output_file
jcmd <PID> JFR.check
jcmd <PID> JFR.dump name=output_file filename=output.jfr
jcmd <PID> JFR.configure repositorypath=/home/jfr/recordings