2 Running Java Flight Recorder

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 visit http://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:

Using the Command Line
Using Diagnostic Commands
Configuring Recordings
Creating Recordings Automatically
Security
Troubleshooting

2.1 Using the Command Line

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".

2.2 Using Diagnostic Commands

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.
$

2.3 Configuring Recordings

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).

2.3.1 Setting Maximum Size and Age

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.

2.3.2 Setting the Delay

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.

2.3.3 Setting Compression

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.

2.4 Creating Recordings Automatically

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.

2.4.1 Creating a Recording On Exit

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.

2.4.2 Creating a Recording Using Triggers

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.

2.5 Security

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 `jcmd` to control the process.
Java Mission Control Client	Java Mission Control Client uses JMX to access the JVM.

2.6 Troubleshooting

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.