jcmd: Collect JFR (Java Flight Recorder) information

In this post, I am going to show you how to collect JFR information using jcmd command.

Step 1: Run the application by enabling JFR (Java Flight Recorder).

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -classpath . HelloWorld

Step 2: Open command prompt and run jcmd command.

C:\>jcmd
14208 sun.tools.jcmd.JCmd
8816 HelloWorld
8456

From the above output, I can confirm that ‘HelloWorld’ application is running with process id 8816.

Run the command ‘jcmd HelloWorld help’.

C:\>jcmd HelloWorld help
8816:
The following commands are available:
JFR.stop
JFR.start
JFR.dump
JFR.check
VM.native_memory
VM.check_commercial_features
VM.unlock_commercial_features
ManagementAgent.stop
ManagementAgent.start_local
ManagementAgent.start
GC.rotate_log
Thread.print
GC.class_stats
GC.class_histogram
GC.heap_dump
GC.run_finalization
GC.run
VM.uptime
VM.flags
VM.system_properties
VM.command_line
VM.version
Help
For more information about a specific command use 'help <command>'.

Following are the jfr specific commands provided by jcmd.

JFR.start : Start a flight recording. Below table summarizes the parameters that are associated with JFR.start command.

Parameter	Description	Type Of value	Default value
delay	Wait time before starting the record	Integer followed by s/m/h. Ex: 5s: 5 Seconds 5m: 5 Minutes 5h: 5 hours	0 seconds
disk	Flag for writing data to disk while recording	Boolean	true
dumponexit	If this flag is set to true, then the recording data is written to the file when the JVM (Java Virtual Machine) shut down. The file name is a system-generated name that contains the process ID, recording ID, and current time stamp. Example : otspot-pid-47496-id-1-2018_01_25_19_10_41.jfr.	Boolean	false
duration	Length of the time to record.	Integer followed by s/m/h. Ex: 5s: 5 Seconds 5m: 5 Minutes 5h: 5 hours	0s
filename	Name (or) absolute path of the file to record the information.	String	No default value.
maxage	Maximum time to keep the recorded data on disk. This parameter is valid only when the disk parameter is set to true.	Integer followed by s/m/h. Ex: 5s: 5 Seconds 5m: 5 Minutes 5h: 5 hours	0s (forever)
maxsize	Maximum size of the data to keep on disk. Format: long value followed by a.   m or M for megabytes b.   g or G for gigabytes 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 the JFR.configure command.	Long	0 (no maximum size)
name	Name of the recording. If no name is provided, a name is generated. This name can be used with other commands	String	System generated name
path-to-gc-roots	Used to collect the path to garbage collection (GC) roots at the end of a recording.	Boolean	false
settings	Name of the settings file that identifies the events to record. How can I specify multiple settings files? Specify the file names/paths separated by comma.	String	JRE_HOME/lib/jfr/default.jfc

Example

jcmd {PID} JFR.start duration=5m settings=demoSettings filename=c:\recordings\appRecordings.jfr

Above statement starts a recording that runs for 5 minutes,  uses the settings file named demoSettings to identify the events to record, and writes the recording to a file named c:\recordings\appRecordings.jfr.

JFR.check: It is used to check the information about the running flight recording.

Below table summarizes the parameters associated with JFR.check parameter.

Parameter	Description	Type of Value	Deafult Value
name	Name of the recorder	String	No default value
verbose	Flag for printing the event settings for the recording	Boolean	false

Example

jcmd {ProcessId} JFR.check name={RecordingName}

JFR.stop: Used to stop the flight recording. Below table summarizes the parameters associated with JFR.stop command.

Parameter	Description	Type of Value	Default Value
filename	Name of the file to which the recording is written when the recording is stopped.	String	No default value
name	Name of the recording	String	No default value

Example

jcmd {PROCESS_ID} JFR.stop name={NAME_OF_THE_RECORDING} filename={FILE_NAME_TO_STORE_RECORDING}

JFR.dump: Used to write the recording data to a file while a fligh recording is running.

Below table summarizes the parameters associated with JFR.dump command.

Parameter	Description	Type of the value	Default value
filename	Name or path of the file to which the recording is written.	String	No default value
name	Name of the recording	String	No default value
path-to-gc-roots	Flag for collecting the path to garbage collection (GC) roots at the time that the recording data is dumped.	Boolean	false

Example

jcmd {PROCESS_ID} JFR.dump name={NAME_OF_THE_RECORDING} filename={FILE_NAME_TO_STORE_RECORDING}

Let’s see how to collect the flight recording information using jcmd.

HelloWorld.java

public class HelloWorld{
 public static void main(String args[])throws Exception{
  Thread t1 = new Thread(){
   public void run(){
    while(true){
     try{
      Thread.sleep(5000);
     }catch(Exception e){
   
     }
    }
   }
  };
  
  t1.start();
 }
}

Compile and run HelloWorld.java. Run the application using below statement.

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -classpath . HelloWorld

Above statement launch HelloWorld application and enables flight recorder.

Open command prompt and execute 'jcmd' command.

C:\>jcmd
17216 sun.tools.jcmd.JCmd
4544 org.apache.chemistry.opencmis.workbench.Workbench
14612 HelloWorld

As you see above output, HelloWorld application is running with process id 14612.

Start flight recording using jcmd

Open command prompt (or) terminal execute below statement.

jcmd 14612 JFR.start duration=5m filename=appRecordings.jfr

Above statement starts the flight recording and store it in appRecordings.jfr

C:\>jcmd 14612 JFR.start duration=5m filename=appRecordings.jfr
14612:
Started recording 1. The result will be written to:

Check flight recording status

Execute the statement ‘jcmd 14612 JFR.check’

C:\> jcmd 14612 JFR.check
14612:
Recording: recording=1 name="appRecordings.jfr" duration=5m filename="appRecordings.jfr" compress=false (running)

As you see above output, recording is still running. Since I do not provided a name to the recording explicitly, java creates recording name as filename.

Wait for 5 minutes and recheck the recording again.

C:\> jcmd 14612 JFR.check
14612:
No available recordings.

Use JFR.start to start a recording.

You can able to see above kind of message.

Go to the directory from where you ran ‘jcmd’ command, you can able to see ‘appRecordings.jfr’ file.

Double click on ‘appRecordings.jfr’ file, it opens below user interface.

Previous                                                 Next                                                 Home