This chapter describes how you can modify or write your own server-side templates.
It contains these sections:
Event types are referenced by relational keys, describing what type of subsystem in the JVM or application they belong to. The relational key for event types for all JVM internal systems start with http://www.oracle.com/jrockit/jvm. The JVM has different subsystems, such as vm which refers to the runtime, os that refers to the operating system it runs on, java which refers to the executing Java program, and so on; for example, the key for the event that is triggered upon the JVM entering a lock at the native level is called:
http://www.oracle.com/jrockit/jvm/vm/sync/mutex_enter
The only other master relational key except for the http://www.oracle.com/jrockit/jvm key you might encounter is http://www.oracle.com/jrockit/jfr-info, which is the "meta producer" for Flight Recorder; that is, event types internal to JRockit Flight Recorder.
Many event types are enabled in the default flight recording, however through server-side templates you can customize this.
A server-side template is a file with the suffix .jfs. It contains data in JSON format, which is used to modify or extend the settings of a flight recording. Normally, you do not need to create your own server-side template but, should you have to do this, you can modify one of the sample templates in the JROCKIT_HOME/jre/lib/jfr folder.
You can pass server-side templates that customize a recording to the Oracle JRockit JVM by using the -XX:FlightRecorderOptions with the settings subflag or by using the start_flightrecording diagnostic command. settings can either be the name of a predefined template (located in JROCKIT_HOME/jre/lib/jfr) or the path to a completely custom template.
Each server-side template consists of a single section, containing mappings of relational keys representing event types to their customized properties. For each event type, you can set the properties enable, stacktrace, threshold, and period:
Set enable to either true or false, depending on whether or not the recording should contain this event.
Set stacktrace to either true or false, depending on if a stack trace should be collected from the point that triggered the event.
Set a threshold for the minimum duration of the event (where applicable) that you want logged.
Set period to how often you want the event triggered (for requestable events); for example how often exception statistics should be gathered for events in the /java/statistics/exceptions event under the key http://www.oracle.com/jrockit/jvm. If period is set to 0 this specifies a constant event; that is, one that is only generated once per recording (such as logging the system properties). Depending on event types, the number of applicable modifiers might vary.
The typical format for a server-side template (.jfs) file is shown in Example A-1:
Example A-1 Typical Format for a Server-side Template
{
<relational-key> : {
<sub-key 1> : {
<attribute> : <value>
<attribute> : <value>
...
<attribute> : <value>
},
...
<sub-key 2> : {
<attribute> : <value>
<attribute> : <value>
...
<attribute> : <value>
},
},
...
}
For readability, the relational key is usually split into several levels; for example, a server-side template enabling more verbose Java I/O information in the recording might look like Example A-2:
Example A-2 Server-side Template Enabling More Verbose Java I/O Information in the Recording
{
"http://www.oracle.com/jrockit/jvm/" : {
// Socket/SocketChannel read/write
"java/socket_*" : {
"enable" : true,
"stacktrace" : true
},
// FileInputStream/RandomAccessFile/FileChannel read/write
"java/file_*" : {
"enable" : true,
"stacktrace" : true
}
}
}
You can use wildcard for attributes and relational keys. In Example A-1, all event types with descriptors starting with http://www.oracle.com/jrockit/jvm/java/socket_ and http://www.oracle.com/jrockit/jvm/java/file_ are enabled (with stack trace recording).
Wildcards can be arbitrarily powerful. For example, in Example A-3, brute force enables collections of all event types, with a minimum period of 1,000 ms to avoid extreme data bloat:
Example A-3 Brute Force Enabling the Collecting of All Event Types
// Settings file for JRockit Flight Recorder enabling collection of all events
{
"*" : {
"enable" : true,
"stacktrace" : true,
"threshold" : 0,
"period" : 1000ms
}
}
You should copy and play around with the pre-installed custom templates available in the JROCKIT_HOME/jre/lib/jfr to get a better understanding of how this works.
The JRockit Flight Recorder repository is made up of multiple files which you might find tedious to open, one after the other, in JRockit Mission Control. You can, however, use a Flight Recorder tool that concatenates all of the recording files in a repository into a single file that you can then open in JRockit Mission Control.
Use the concatenation tool by entering this command:
java oracle.jrockit.jfr.tools.ConCatRepository [directory] [-o output_filename] [-f]
If no arguments are given, the tool creates a file based on the timestamps from the chunk files in the current directory.
If directory is specified, that directory is used as repository.
If -o output_filename is specified, the resulting file is named output_filename.
If -f is specified, any existing file with the same name is overwritten.