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.