Top Description Interfaces Annotations Classes Enums
module jdk.jfr

Package jdk.jfr

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

Defining events

Flight Recorder collects data as events. An event has a time stamp, duration and usually an application-specific payload, useful for diagnosing the running application up to the failure or crash.

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

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

Gathering data to store in an event can be expensive. The jdk.jfr.Event#shouldCommit() method can be used to verify whether an event instance would actually be written to the system when the jdk.jfr.Event#commit() method is invoked. If jdk.jfr.Event#shouldCommit() returns false, then those operations can be avoided.

Sometimes the field layout of an event is not known at compile time. In that case, an event can be dynamically defined. However, dynamic events might not have the same level of performance as statically defined ones and tools might not be able to identify and visualize the data without knowing the layout.

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

Controlling Flight Recorder

Flight Recorder can be controlled locally by using the jcmd command line tool or remotely by using the FlightRecorderMXBean interface, registered in the platform MBeanServer. When direct programmatic access is needed, a Flight Recorder instance can be obtained by invoking jdk.jfr.FlightRecorder#getFlightRecorder() and a recording created by using jdk.jfr.Recording class, from which the amount of data to record is configured.

Settings and configuration

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

The name can be formed in the following 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, use the name "jdk.CPULoad#period" and the value "1 s". If multiple events use the same name, for example if an event class is loaded in multiple class loaders, and differentiation is needed between them, then the name is "56#period". The ID for an event is obtained by invoking jdk.jfr.EventType#getId() method and is valid for the Java Virtual Machine instance that the event is registered in.

A list of available event names is retrieved by invoking jdk.jfr.FlightRecorder#getEventTypes() and jdk.jfr.EventType#getName(). A list of available settings for an event type is obtained by invoking jdk.jfr.EventType#getSettingDescriptors() and jdk.jfr.ValueDescriptor#getName().

Predefined settings

Event setting names and their purpose.
Name Description Default value Format Example values
enabled Specifies whether the event is recorded "true" String representation of a Boolean ("true" or "false") "true"
"false"
threshold Specifies the duration below which an event is not recorded "0" (no limit) "0" if no threshold is used, otherwise a string representation of a positive Long followed by a 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 Specifies the interval at which the event is 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 Specifies whether the stack trace from the Event#commit() method is 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

Interface Summary

Modifier and TypeInterface and Description
public interface
FlightRecorderListener

Callback interface to monitor Flight Recorder's life cycle.

Annotation Summary

Modifier and TypeAnnotation and Description
public @interface
BooleanFlag

Event field annotation, specifies that the value is a boolean flag, a true or false value.

public @interface
Category

Event annotation, to associate the event type with a category, in the format of a human-readable path.

public @interface
ContentType

Meta annotation, specifies that an annotation represents a content type, such as a time span or a frequency.

public @interface
DataAmount

Event field annotation, specifies that a value represents an amount of data (for example, bytes).

public @interface
Description

Annotation that describes an element by using a sentence or two.

public @interface
Enabled

Event annotation, determines if an event should be enabled by default.

public @interface
Experimental

Annotation that specifies that an element is experimental and may change without notice.

public @interface
Frequency

Event field annotation, specifies that the value is a frequency, measured in Hz.

public @interface
Label

Annotation that sets a human-readable name for an element (for example, "Maximum Throughput").

public @interface
MemoryAddress

Event field annotation, specifies that the value is a memory address.

public @interface
MetadataDefinition

Meta annotation for defining new types of event metadata.

public @interface
Name

Annotation that sets the default name for an element.

public @interface
Percentage

Event field annotation to use on fractions, typically between 0.0 and 1.0, to specify that the value is a percentage.

public @interface
Period

Event annotation, specifies the default setting value for a periodic event.

public @interface
Registered

Event annotation, for programmatic event registration.

public @interface
Relational

Meta annotation for relational annotations, to be used on an annotation.

public @interface
SettingDefinition

Annotation that specifies that a method in an event class should be used to filter out events.

public @interface
StackTrace

Event annotation, determines whether an event by default has a stack trace or not.

public @interface
Threshold

Event annotation, specifies the default duration below which an event is not recorded (for example, "20 ms").

public @interface
Timespan

Event field annotation, specifies that the value is a duration.

public @interface
Timestamp

Event field annotation, specifies that the value is a point in time.

public @interface
TransitionFrom

Event field annotation, specifies that the event transitioned from a thread.

public @interface
TransitionTo

Event field annotation, specifies that the event will soon transition to a thread.

public @interface
Unsigned

Event field annotation, specifies that the value is of an unsigned data type.

Class Summary

Modifier and TypeClass and Description
public class
AnnotationElement

Describes event metadata, such as labels, descriptions and units.

public class
Configuration

A collection of settings and metadata describing the configuration.

public abstract class
Event

Base class for events, to be subclassed in order to define events and their fields.

public class
EventFactory

Class for defining an event at runtime.

public abstract class
EventSettings

Convenience class for applying event settings to a recording.

public class
EventType

Describes an event, its fields, settings and annotations.

public class
FlightRecorder

Class for accessing, controlling, and managing Flight Recorder.

public class
FlightRecorderPermission

Permission for controlling access to Flight Recorder.

public class
Recording

Provides means to configure, start, stop and dump recording data to disk.

public abstract class
SettingControl

Base class to extend to create setting controls.

public class
SettingDescriptor

Describes an event setting.

public class
ValueDescriptor

Describes the event fields and annotation elements.

Enum Summary

Modifier and TypeEnum and Description
public enum
RecordingState

Indicates a state in the life cycle of a recording.