Module jdk.jfr

Package jdk.jfr

This package contains classes to create events and control Flight Recorder.

Defining events

Flight Recorder data is stored in events. An event has a timestamp, duration and usually an application specific payload, useful for diagnosing the application up to the failure/crash.

To define a Flight Recorder event, extend Event and add fields matching the data types of the payload that should be recorded. Metadata about fields, such as labels, descriptions and units, can be added using annotations available in the jdk.jfr.annotation package, or a user-defined annotation can be used (if it has the MetadataDefinition annotation).

Once an event class has been defined, individual instances can be created (event objects). Data is stored to the event by assigning to fields. Event timing can be explicitly controlled by using the begin and end methods available in the Event class.

To actually store data into the Flight Recorder system, use the Event.commit() method. If gathering data in order to store to an event would be relative expensive, an application can use the Event.shouldCommit() to branch if the event would be committed on an invocation to commit, thus avoiding expensive operations unnecessarily.

Sometimes the field layout of an event is not known at compile time. If that is the case, an event can be dynamically defined. However, dynamic events have a couple of drawbacks, they might not have the same performance as statically defined ones and it's usually hard for tools to identify and visualize the data without knowing the layout.

To define an event dynamically, use EventFactory and define fields using the ValueDescriptor class and annotations using the AnnotationElement class. Use the factory to allocate an event and the Event.set(int, Object) method to populate it.

Controlling Flight Recorder

Flight Recorder can be controlled using the jcmd command line tool or via JMX using the FlightRecorderMXBean, registered in the platform MBeanServer. This is usually sufficient for most use cases, but if direct programmatic access is needed, an instance can be obtained by invoking FlightRecorder.getFlightRecorder(). With a Flight Recorder instance, a Recording can be created, from which the amount of data to record can be configured.

Settings and configuration

A setting consists of a name value pair, where the name specifies which event and setting to configure, and the value determines what it should be set to.

The name can be formed in two ways,

<event-name> + "#" + <setting-name>

or

<event-id> + "#" + <setting-name>

For example, to set the sample interval of the CPU Load event to once every second, the name should be "com.oracle.jdk.CPULoad#period" and the value "1 s". If multiple events use the same name, for instance if an event class is loaded in multiple class loaders, and differentiation is needed between them, the second form can be used, for example "56#period". The id for an event can be obtained by invoking EventType.getId() and is only valid for the JVM instance the event was registered in.

A list of available event names can be retrieved by calling FlightRecorder.getEventTypes() and EventType.getName(). A list of available settings for an event type can be obtained by invoking EventType.getSettingDescriptors() and ValueDescriptor.getName().

The JDK comes with following predefined settings.

Event setting names and their purpose.
Name Description Default value Format Example values
enabled If event should be recorded at all "true" String representation of a Boolean ("true" or "false") "true",
"false"
threshold Cut-off below which event should not be recorded "0" (no limit) "0" if no threshold should be used, otherwise a string representation of a positive Long followed by an empty space and one of the following units:
  • "ns" (nanoseconds)
  • "us" (microseconds)
  • "ms" (milliseconds)
  • "s" (seconds)
  • "m" (minutes)
  • "h" (hours)
  • "d" (days)
"0",
"10 ms",
"1 s"
period Interval at which the event should be emitted, if it is periodic. "everyChunk" "everyChunk", if a periodic event should be emitted with every file rotation, otherwise a string representation of a positive Long value followed by an empty space and one of the following units:
  • "ns" (nanoseconds)
  • "us" (microseconds)
  • "ms" (milliseconds)
  • "s" (seconds)
  • "m" (minutes)
  • "h" (hours)
  • "d" (days)
"20 ms",
"1 s",
"everyChunk"
stackTrace If the stack trace from the Event#commit() method should be recorded "true" String representation of a Boolean ("true" or "false") "true",
"false"

Null-handling

All methods define whether they accept or return null in the Javadoc. Typically this is expressed as "not null". If a null parameter is used where it is not allowed, a java.lang.NullPointerException is thrown. If a null parameters is passed to a method that throws other exceptions, such as java.io.IOException, the java.lang.NullPointerException takes precedence, unless the Javadoc for the method explicitly states how null is handled, i.e. by throwing java.lang.IllegalArgumentException.

Since:
9
Commercial feature
This is a commercial feature that must be unlocked before being used. To learn more about commercial features and how to unlock them visit http://www.oracle.com/technetwork/java/javaseproducts/.