public abstract class Event
extends java.lang.Object
The following example shows how to implement an Event class.
import jdk.jfr.Event;
import jdk.jfr.Description;
import jdk.jfr.Label;
public class Example {
@Label("Hello World")
@Description("Helps programmer getting started")
static class HelloWorld extends Event {
@Label("Message")
String message;
}
public static void main(String... args) {
HelloWorld event = new HelloWorld();
event.message = "hello, world!";
event.commit();
}
}
After an event is allocated and its field members are populated, it can be
written to the Flight Recorder system by using the #commit() method.
By default, an event is enabled. To disable an event annotate the
Event class with @Enabled(false).
Supported field types are the Java primitives: boolean, char,
byte, short, int, long, float, and
double. Supported reference types are: String, Thread
and Class. Arrays, enums, and other reference types are silently
ignored and not included. Fields that are of the supported types can be
excluded by using the transient modifier. Static fields, even of the
supported types, are not included.
Tools can visualize data in a meaningful way when annotations are used (for
example, Label, Description, and Timespan).
Annotations applied to an Event class or its fields are included if
they are present (indirectly, directly, or associated), have the
MetadataDefinition annotation, and they do not contain enums, arrays,
or classes.
Gathering data to store in an event can be expensive. The
shouldCommit() method can be used to verify whether an event
instance would actually be written to the system when the
Event#commit()commit method is invoked. If
shouldCommit() returns false, then those operations can be
avoided.
| Modifier | Constructor and Description |
|---|---|
protected |
Event()
Sole constructor, for invocation by subclass constructors, typically
implicit.
|
| Modifier and Type | Method and Description |
|---|---|
void |
begin()
Starts the timing of this event.
|
void |
commit()
Writes the field values, time stamp, and event duration to the Flight
Recorder system.
|
void |
end()
Ends the timing of this event.
|
boolean |
isEnabled()
Returns
true if at least one recording is running, and the
enabled setting for this event is set to true, otherwise
false is returned. |
void |
set(int index,
java.lang.Object value)
Sets a field value.
|
boolean |
shouldCommit()
Returns
true if the enabled setting for this event is set to
true and if the duration is within the threshold for the event,
false otherwise. |
protected Event()
public final void begin()
public final void end()
end method must be invoked after the begin method.public final void commit()
If the event starts with an invocation of the begin method, but does
not end with an explicit invocation of the end method, then the event
ends when the commit method is invoked.
public final boolean isEnabled()
true if at least one recording is running, and the
enabled setting for this event is set to true, otherwise
false is returned.true if event is enabled, false otherwisepublic final boolean shouldCommit()
true if the enabled setting for this event is set to
true and if the duration is within the threshold for the event,
false otherwise. The threshold is the minimum threshold for all
running recordings.true if the event can be written to the Flight Recorder
system, false otherwisepublic final void set(int index,
java.lang.Object value)
Applicable only if the event is dynamically defined using the
EventFactory class.
The supplied index corresponds to the index of the
ValueDescriptor object passed to the factory method of the
EventFactory class.
index - the index of the field that is passed to
EventFactory#create(String, java.util.List, java.util.List)value - value to set, can be nulljava.lang.UnsupportedOperationException - if it's not a dynamically generated
eventjava.lang.IndexOutOfBoundsException - if index is less than 0 or
greater than or equal to the number of fields specified for the eventEventType.getFields(),
EventFactory