This chapter describes how to start the Java Flight Recorder for both default and explicit recordings from a command line.
This chapter contains these sections:
Java Flight Recorder allows many recordings to run concurrently. You can configure each recording by 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 a little bit confusing but has no other negative implications.
By using Java Flight Recorder, you can create an explicit recording; that is, one you start explicitly and let run for some predetermined length of time or until you manually stop it. This section describes how to do this.
Regardless of the method you use to start a recording, the same set of parameters are available. You can use any of the following tools to control explicit recordings:
The simplest way to control Java Flight Recorder is by using the Java Mission Control client. For more information, see Section 2.1, "Using Java Mission Control Client".
You can start and configure a recording from the command line by using the -XX:StartFlightRecording option of the java command, when starting the application. To enable the use of Java Flight Recorder, specify the -XX:+FlightRecorder option. Because Java Flight Recorder 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 Java Flight Recorder, you can use the -XX:FlightRecorderOptions option. For more information, see Section A.1, "Command-Line Options."
You can also control recordings by using Java-specific diagnostic commands. For a more detailed description of Diagnostic Commands, see Section A.2, "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 identificator 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 identificator 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 identificator (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, etc.
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 |
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). This section contains the following information:
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. This section includes the following information:
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 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 JRockit Mission Control Console's MBean page. For more information on how to create triggers, see the online help in Java Mission Control.
