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:

2.1 Using the Command Line

You can start and configure a recording from the command line using the -XX:StartFlightRecording option of the java command, when starting the application. To enable the use of JFR, specify the -XX:+FlightRecorder option. Because JFR is a commercial feature, you also have to specify the -XX:+UnlockCommercialFeatures option. The following example illustrates how to run the MyApp application and immediately start a 60-second recording which will be saved to a file named myrecording.jfr:

java -XX:+UnlockCommercialFeatures -XX:+FlightRecorder -XX:StartFlightRecording=duration=60s,filename=myrecording.jfr MyApp

To configure JFR, you can use the -XX:FlightRecorderOptions option. For more information, see Appendix A, "Command-Line Options".

2.2 Using Diagnostic Command

You can also control recordings by using Java-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 have to 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 runnning Java application, specify help as the diagnostic command after the process identifier (or the name of the main class). The commands relevant to Java Flight Recorder are:

  • JFR.start

    Start a recording.

  • JFR.check

    Check the status of all recordings running for the specified process, including the recording identification number, file name, duration, and so on.

  • JFR.stop

    Stop a recording with a specific identification number (by default, recording 1 is stopped).

  • JFR.dump

    Dump the data collected so far by the recording with a specific identification number (by default, data from recording 1 is dumped).

Note:

These commands are available only if the Java application was started with the Java Flight Recorder enabled, that is, using the following options: 
-XX:+UnlockCommercialFeatures -XX:+FlightRecorder

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.

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

Java Flight Recorder is intended only for diagnostic purposes. 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.