Skip Headers
Oracle® JRockit Flight Recorder Run Time Guide
Release R28

Part Number E15070-09
Go to Documentation Home
Home
Go to Table of Contents
Contents
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

A Creating Your Own Server-side Templates

This chapter describes how you can modify or write your own server-side templates.

It contains these sections:

A.1 Event Types and Relational Keys

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.

A.2 Server-side Templates

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.

A.3 File Format

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:

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.

A.4 Concatenation Tool

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]