This chapter describes how you can run Java Flight Recorder.
Note:
Java Flight Recorder requires a commercial license for use in production. To learn more about commercial features and how to enable them please visithttp://www.oracle.com/technetwork/java/javaseproducts/
.You can run multiple recordings concurrently and configure each recording using different settings; in particular, you can configure different recordings to capture different sets of events. However, in order to make the internal logic of Java Flight Recorder as streamlined as possible, the resulting recording always contains the union of all events for all recordings active at that time. This means that if more than one recording is running, you might end up with more information in the recording than you wanted. This can be confusing but has no other negative implications.
The easiest and most intuitive way to use JFR is through the Flight Recorder plug-in that is integrated into Java Mission Control. This plug-in enables access to JFR functionality through an intuitive GUI. For more information about using the JMC client to control JFR, see the Flight Recorder Plug-in section of the Java Mission Control help.
This chapter explains more advanced ways of running and managing JFR recordings and contains the following sections:
Before creating a flight recording, you must first unlock commercial features and enable Java Flight Recorder. This can be done in a variety of ways, ranging from java
command line options, to jcmd
diagnostic commands, to Graphical User Interface (GUI) controls within Java Mission Control. This flexibility enables you to provide the appropriate options at startup, or interact with JFR later, after the JVM is already running.
The following example uses java
command-line options to run MyApp
and immediately start a 60-second recording. The recording will be saved to a file named myrecording.jfr
:
java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:StartFlightRecording=duration=60s,filename=myrecording.jfr MyApp
For more information about the supported command-line options, see Appendix A, "Command-Line Options".
It is possible to control recordings using jcmd
and JFR-specific diagnostic commands. For a more detailed description of Diagnostic Commands, see Appendix A, "Diagnostic Command Reference".
The simplest way to execute a diagnostic command is to use the jcmd
tool (located in the Java installation directory). To issue a command, you must pass the process identifier of the JVM (or the name of the main class) and the actual command as arguments to jcmd
.
For example, to start a 60-second recording on the running Java process with the identifier 5368 and save it to myrecording.jfr
in the current directory, use the following:
jcmd 5368 JFR.start duration=60s filename=myrecording.jfr
To see a list of all running Java processes, run the jcmd
command without any arguments. To see a complete list of commands available to a running Java application, specify help
as the diagnostic command after the process identifier (or the name of the main class).
The following examples show various use cases for running jcmd
with Java Flight Recorder, assuming a demo program that lives in MyApp.jar
.
Example 2-1 Dynamic Interaction Using jcmd
Example 2-1 unlocks commercial features and enables Java Flight Recorder dynamically at runtime. No extra options are provided when the Java application is launched. Once the JVM is running, the jcmd
commands VM.unlock_commercial_features
and JFR.start
are used to unlock commercial features and start a new flight recording.
$java -jar MyApp.jar $jcmd 40019 VM.command_line 40019: VM Arguments: java_command: MyApp.jar java_class_path (initial): MyApp.jar Launcher Type: SUN_STANDARD $jcmd 40019 VM.check_commercial_features 40019: Commercial Features are locked. $jcmd 40019 JFR.check 40019: Java Flight Recorder not enabled. Use VM.unlock_commercial_features to enable. $jcmd 40019 VM.unlock_commercial_features 40019: Commercial Features now unlocked. $jcmd 40019 VM.check_commercial_features 40019: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has not been used. Resource Management is disabled. $jcmd 40019 JFR.check 40019: No available recordings. Use JFR.start to start a recording. $jcmd 40019 JFR.start name=my_recording filename=myrecording.jfr dumponexit=true 40019: Started recording 1. No limit (duration/maxsize/maxage) in use. Use JFR.dump name=my_recording to copy recording data to file. $jcmd 40019 VM.check_commercial_features 40019: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has been used. Resource Management is disabled. $jcmd 40019 JFR.check 40019: Recording: recording=1 name="my_recording" filename="myrecording.jfr" compress=false (running) $
Example 2-2 Using -XX:+UnlockCommercialFeatures and -XX:+FlightRecorder
Example 2-2 unlocks commercial features and enables JFR by passing options -XX:+UnlockCommercialFeatures
and -XX:+FlightRecorder
to the java
command when the application starts.
$java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -jar MyApp.jar $jcmd 37152 VM.command_line 37152: VM Arguments: jvm_args: -XX:+UnlockCommercialFeatures -XX:+FlightRecorder java_command: MyApp.jar java_class_path (initial): MyApp.jar Launcher Type: SUN_STANDARD $jcmd 37152 VM.check_commercial_features 37152: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has not been used. Resource Management is disabled. $jcmd 37152 JFR.check 37152: No available recordings. Use JFR.start to start a recording. $jcmd 37152 JFR.start name=my_recording filename=myrecording.jfr dumponexit=true 37152: Started recording 1. No limit (duration/maxsize/maxage) in use. Use JFR.dump name=my_recording to copy recording data to file. $jcmd 37152 JFR.check 37152: Recording: recording=1 name="my_recording" filename="myrecording.jfr" compress=false (running) $jcmd 37152 VM.check_commercial_features 37152: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has been used. Resource Management is disabled. $
Example 2-3 Using -XX:+UnlockCommercialFeatures with a JFR Dynamic Start
Example 2-3 starts JFR dynamically (using JFR.start
) after the application has been launched with -XX:+UnlockCommercialFeatures
.
$java -XX:+UnlockCommercialFeatures -jar MyApp.jar $jcmd 39970 VM.command_line 39970: VM Arguments: jvm_args: -XX:+UnlockCommercialFeatures java_command: MyApp.jar java_class_path (initial): MyApp.jar Launcher Type: SUN_STANDARD $jcmd 39970 VM.check_commercial_features 39970: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has not been used. Resource Management is disabled. $jcmd 39970 JFR.check 39970: No available recordings. Use JFR.start to start a recording. $jcmd 39970 VM.check_commercial_features 39970: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has not been used. Resource Management is disabled. $jcmd 39970 JFR.start name=my_recording filename=myrecording.jfr dumponexit=true 39970: Started recording 1. No limit (duration/maxsize/maxage) in use. Use JFR.dump name=my_recording to copy recording data to file. $jcmd 39970 VM.check_commercial_features 39970: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has been used. Resource Management is disabled. $jcmd 39970 JFR.check 39970: Recording: recording=1 name="my_recording" filename="myrecording.jfr" compress=false (running) $
Example 2-4 Locking Commercial Features with -XX:-UnlockCommercialFeatures
Example 2-4 launches the application with commercial features explicitly locked (-XX:-UnlockCommercialFeatures
). It then unlocks commercial features with VM.unlock_commercial_features
, and starts a new flight recording with JFR.start
.
$ java -XX:-UnlockCommercialFeatures -jar MyApp.jar $jcmd 40110 VM.command_line 40110: VM Arguments: jvm_args: -XX:-UnlockCommercialFeatures java_command: MyApp.jar java_class_path (initial): MyApp.jar Launcher Type: SUN_STANDARD $jcmd 40110 VM.check_commercial_features 40110: Commercial Features are locked. $jcmd 40110 VM.unlock_commercial_features 40110: Commercial Features now unlocked. $jcmd 40110 VM.check_commercial_features 40110: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has not been used. Resource Management is disabled. $jcmd 40110 JFR.start name=my_recording filename=myrecording.jfr dumponexit=true 40110: Started recording 1. No limit (duration/maxsize/maxage) in use. Use JFR.dump name=my_recording to copy recording data to file. $jcmd 40110 JFR.check 40110: Recording: recording=1 name="my_recording" filename="myrecording.jfr" compress=false (running) $jcmd 40110 VM.check_commercial_features 40110: Commercial Features are unlocked. Status of individual features: Java Flight Recorder has been used. Resource Management is disabled.$
Example 2-5 Disabling JFR with -XX:-FlightRecorder
Example 2-5 disables JFR entirely by passing -XX:-FlightRecorder
to the java
command when the application starts. It is not possible to dynamically create a new flight recording if this option has been specified.
$java -XX:+UnlockCommercialFeatures -XX:-FlightRecorder -jar MyApp.jar $jcmd 39589 VM.command_line 39589: VM Arguments: jvm_args: -XX:+UnlockCommercialFeatures -XX:-FlightRecorder java_command: MyApp.jar java_class_path (initial): MyApp.jar Launcher Type: SUN_STANDARD $jcmd 39589 VM.check_commercial_features 39589: Commercial Features are unlocked. Status of individual features: Java Flight Recorder is disabled. Resource Management is disabled. $jcmd 39589 JFR.check 39589: Java Flight Recorder is disabled. $jcmd 39589 JFR.stop 39589: Java Flight Recorder is disabled. $jcmd 39589 VM.unlock_commercial_features 39589: Commercial Features already unlocked. $jcmd 39589 JFR.start name=my_recording filename=myrecording.jfr dumponexit=true 39589: Java Flight Recorder is disabled. $
Example 2-6 Invalid Option Combinations
Example 2-6 shows what happens when invalid option combinations are passed to the java
command. In this case, the user attempts to enable JFR (-XX:+FlightRecorder
) with simultaneously locking commercial features (-XX:-UnlockCommercialFeatures
).
$ java -XX:-UnlockCommercialFeatures -XX:+FlightRecorder -jar MyApp.jar Error: To use 'FlightRecorder', first unlock using -XX:+UnlockCommercialFeatures. Error: Could not create the Java Virtual Machine. Error: A fatal exception has occurred. Program will exit. $
You can configure an explicit recording in a number of other ways. These techniques work the same regardless of how you start a recording (that is, either by using the command-line approach or by using diagnostic commands).
You can configure an explicit recording to have a maximum size or age by using the following parameters:
maxsize=size
Append the letter k
or K
to indicate kilobytes, m
or M
to indicate megabytes, g
or G
to indicate gigabytes, or do not specify any suffix to set the size in bytes.
maxage=age
Append the letter s
to indicate seconds, m
to indicate minutes, h
to indicate hours, or d
to indicate days.
If both a size limit and an age are specified, the data is deleted when either limit is reached.
When scheduling a recording. you might want to add a delay before the recording is actually started; for example, when running from the command line, you might want the application to boot or reach a steady state before starting the recording. To achieve this, use the delay
parameter:
delay=delay
Append the letter s
to indicate seconds, m
to indicate minutes, h
to indicate hours, or d
to indicate days.
Although the recording file format is very compact, you can compress it further by adding it to a ZIP archive. To enable compression, use the following parameter:
compress=true
Note that CPU resources are required for the compression, which can negatively impact performance.
When running with a default recording you can configure Java Flight Recorder to automatically save the current in-memory recording data to a file whenever certain conditions occur. If a disk repository is used, the current information in the disk repository will also be included.
To save the recording data to the specified path every time the JVM exits, start your application with the following option:
-XX:FlightRecorderOptions=defaultrecording=true,dumponexit=true,dumponexitpath=path
Set path to the location where the recording should be saved. If you specify a directory, a file with the date and time as the name is created in that directory. If you specify a file name, that name is used. If you do not specify a path, the recording will be saved in the current directory.
You can also specify dumponexit=true
as a parameter to the -XX:StartFlightRecording
option:
-XX:StartFlightRecording=name=test,filename=D:\test.jfr,dumponexit=true
In this case, the dump file will be written to the location defined by the filename parameter.
You can use the Console in Java Mission Control to set triggers. A trigger is a rule that executes an action whenever a condition specified by the rule is true. For example, you can create a rule that triggers a flight recording to commence whenever the heap size exceeds 100 MB. Triggers in Java Mission Control can use any property exposed through a JMX MBean as the input to the rule. They can launch many other actions than just Flight Recorder dumps.
Define triggers on the Triggers tab of the JMX Console. For more information on how to create triggers, see the Java Mission Control help.
The recording file can potentially contain confidential information such as Java command-line options and environment variables. Use extreme care when you store or transfer the recording files as you would do with diagnostic core files or heap dumps.
Table 2-1 describes security permissions for various methods of using JFR.
Table 2-1 Security Permissions
Method | Security |
---|---|
Command line |
Anyone with access to the command line of the Java process must be trusted. |
Diagnostic commands |
Only the owner of the Java process can use |
Java Mission Control Client |
Java Mission Control Client uses JMX to access the JVM. |
You can collect a significant amount of diagnostic information from Java Flight Recorder by starting the JVM with one of the following options:
-XX:FlightRecorderOptions=loglevel=debug
-XX:FlightRecorderOptions=loglevel=trace
.