This chapter describes how to start the JRockit Flight Recorder for both default and explicit recordings from a command line.
This chapter contains these sections:
JRockit 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 the 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.
The default recording is the recording that starts automatically, without you setting any parameters. This section shows you how to start the default recording and how to configure disk storage for that recording. It includes the following information:
As mentioned in Section 3.2, "Running the Default Recording", Oracle JRockit can have a default recording running in the background at all times. In the current release of Oracle JRockit, this is turned off by default but you can easily enable it by using the start-up command -XX:FlightRecorderOptions. In fact, because the performance impact is so low and the value of the data so high, Oracle recommends that you enable a default recording even in production environments. To enable an in-memory black box recording of the JVM, use the following command-line option:
-XX:FlightRecorderOptions=defaultrecording=true
By adding certain parameters to the -XX:FlightRecorderOptions start-up command, you can configure the location of the disk repository as well as the amount of data stored in the repository.
By default, JRockit Flight Recorder stores the temporary recording files in the path specified by the java.io.tmpdir system property, but you can change this by adding this parameter:
repository=<path>
<path> is the preferred repository location; for example, /var/log/jfr.
You can configure the amount of data stored by the default recording in the repository as an absolute amount of bytes by using the maxsize option. For example, you can set this option to use 100 MB of disk space for storing the recording data.
You can also mention that you always want to store certain minutes or hours worth of data by using the maxage option. In this case, JRockit Flight Recorder only discards data when it is older than the specified age. This is a very powerful way of ensuring that data always exists for at least some time leading up to a problem.
If you do not specify any values for maxsize and maxage, the default values are taken. For more information about these options, see the description of -XX:FlightRecorderOptions in Oracle JRockit Command Line Reference.
To set the maximum size, use the maxsize option as follows:
maxsize=<size>
size can be specified with k (kilobytes), m (megabytes) and g (gigabytes) suffixes; for example, 5m.
To set the maximum age, use the maxage option as follows:
maxage=<age>
age can be specified by s (seconds), m (minutes), h (hours), or d (days); for example, 10s. The default value is 15 minutes.
To enable a default recording that stores temporary data in the /var/log/jfr directory and that covers at least the last five minutes of an application run, use the following command-line option:
-XX:FlightRecorderOptions=defaultrecording=true,disk=true,repository=/var/log/jfr,maxage=5m
By default, the recording will be saved in the current working directory.
In addition to the default recording, 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. It includes the following information:
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 JRockit Flight Recorder is by using the JRockit Mission Control client. For more information, see Section 2.1, "Using JRockit Mission Control Client".
You can start and configure a recording from the command-line by using the -XX:StartFlightRecording start-up option:
-XX:StartFlightRecording=duration=<duration>,filename=<filename>
This command will start a recording immediately when the JVM starts. The recording then runs for the specified duration and will be saved to the given filename; for example, to starts a 60-second recording and to save the result in myrecording.jfr in the current directory, use this command:
-XX:StartFlightRecording=duration=60s,filename=myrecording.jfr
You can use several other options to further configure an explicit recording. For more information, see Section B.1, "Start-up Commands" or the Oracle JRockit Command Line Reference, available on the Oracle Technology Network.
You can also control recordings by using JRockit-specific diagnostic commands. For a more detailed description of Diagnostic Commands, see Section B.2, "Diagnostic Command Reference". The simplest way to execute a diagnostic command is to use the JROCKIT_HOME/bin/jrcmd (or JROCKIT_HOME\bin\jrcmd.exe) executable in the JRockit installation. Issue a diagnostic command with jrcmd in the following format:
jrcmd <pid> <command>
Where <pid> is the PID for the JVM to which to send the command and <command> is the diagnostic command itself.
Note:
If you execute jrcmd without any parameters, Oracle JRockit will return a list the running Java processes and their PIDs.You can see a list of available commands by typing:
jrcmd <pid> help
In this list, you will most likely find the relevant commands start_flightrecording, check_flightrecording, and stop_flightrecording.
To get detailed help for a commend, type:
jrcmd <pid> help <command>
For more information on using jrcmd, see "Using jrcmd" in the Oracle JRockit JDK Tools.
Diagnostic commands allow you to start a flight recording in a running JRockit instance. For example, to initiate a 60 second recording and save it to myrecording.jfr in the current directory, you would enter this jrcmd command:
jrcmd <pid> start_flightrecording duration=60s filename=myrecording.jfr
To see which recordings are currently running and the status of each, use the check_flightrecording command. For example, if you type:
jrcmd <pid> check_flightrecording
and execute it before a recording ends, information similar to the following is displayed:
recording : id=1 name="myrecording.jfr" duration=60s dest="myrecording.jfr" compress=false (running)
This indicates that the recording is still running.
If a recording was started with the duration option, it will automatically stop after that time. You can also start a recording without specifying a duration, in which case it will run until explicitly stopped. Do this by using the stop_flightrecording diagnostic command:
jrcmd <pid> stop_flightrecording recording=1
The recording parameter indicates which recording to stop and its value is the id, as seen in the output of check_flightrecording.
You can configure an explicit recording in a number of other ways. These techniques work the same regardless of how you started the recording; that is, either by using the command-line approach or by using diagnostic commands. This section contains the following information:
Like a default recording, you can configure an explicit recording to have a maximum size or age. For a more in-depth discussion of these concepts, see Section 3.2.2, "Configuring Disk Storage". You can configure size and age at startup by using the following parameters:
To set the maximum size:
maxsize=<size>
size can be specified with the k (kilobytes), m (megabytes) and g (gigabytes) suffixes; for example, 10m.
To set the maximum age:
maxage=<age>
age can be specified by s (seconds), m (minutes), h (hours), or d (days); for example, 10s.
If both a size limit and an age are specified, the data is deleted when it is older than the age or when the size limit is exceeded.
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>
Specify the delay period with s (seconds), m (minutes), h (hours), or d (days); for example, 10s.
Although the recording file format is very compact, you can compress it further by zipping the recording. To cause this to happen automatically, use the following parameter:
compress=true
Note that quite a bit of CPU power is required to do the compression which means that compressing recordings can negatively impact performance.
When running with a default recording you can configure JRockit 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 every time the JVM exits, use this command:
-XX:FlightRecorderOptions=dumponexit=true,dumponexitpath=<path>
Set <path> to the location where the recording should be saved. If you specify a directory, a file with a unique 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.
To create a recording when an unhandled exception occurs (that is, an exception that is not caught by any exception handlers in a thread, resulting in the thread terminating) use the -XX:+FlightRecordingDumpOnUnhandledException start-up command.
Specify the location for the recording dump by using the -XX:FlightRecordingDumpPath=<path> start-up command:
The same rules for <path> apply as in Section 3.5.1, "Creating a Recording On Exit".
You can use the Console in JRockit 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 JRockit 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 JRockit Mission Control.
In addition to the automatically dumping recording data from a running default recording, you can also do it manually by using the following diagnostic command:
jrcmd <jrockit pid> dump_flightrecording id=<id> copy_to_file=<path>
This dumps the currently available data for the recording identified by the given <id> to the file given in <path>. You can automatically compress the dumped recording by adding:
compress_copy=true
For more information about the diagnostic command, see Section B.2, "Diagnostic Command Reference".
Additionally, you can use JRockit Mission Control Client to dump recording data. Do the following:
Right-click a JVM in the JVM Browser on the Mission Control Console.
Select Dump Default Recording…