Class Event

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

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.