Module jdk.jfr
Package jdk.jfr

Class Event

  • public abstract class Event
extends Object
    Base class for events, to be subclassed in order to define events and their fields.

    Example, 

     
 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 hwe = new HelloWorld();
       hwe.message = "hello, world!";
       hwe.commit();
   }
 }

    Once an event has been allocated and its field members populated, it can be committed to the Flight Recorder system using the commit() method.

    Events are enabled by default, but can be disabled by annotating the event class with @Enabled(false).

    Supported field types are the Java primitives: boolean, char, byte, short, int, long, float and double. Additionally the following reference types are supported: String, Thread and Class. Arrays, enums and other reference types will be 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.

    In order for tools to visualize data in a meaningful way, use annotations, for example: Label, Description and Timespan. Annotations applied to event classes or its fields will be included if they are present (indirectly, directly or associated), have the MetadataDefinition annotation and they do not contain enums, arrays or classes.

    If performing data gathering operations, in order to populate an event, is considered expensive, the shouldCommit() method can be used to pre-check if this event instance would actually be written to the system when commit() is invoked. If shouldCommit() returns false , then those operations can be avoided.

    Since:
    9

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      protected Event()
      Sole constructor.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void begin()
      Starts timing of this event.
      void commit()
      Writes field values, timestamp and event duration to the Flight Recorder system.
      void end()
      Ends 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, Object value)
      Sets a field value, only applicable if the event is dynamically defined using EventFactory.
      boolean shouldCommit()
      Returns true if event is enabled and if the duration, time elapsed between an invocation to begin and end, is within the threshold for the event, otherwise false is returned.

    • Constructor Detail

      • Event

        protected Event()
        Sole constructor. (For invocation by subclass constructors, typically implicit.)

    • Method Detail

      • begin

        public final void begin()
        Starts timing of this event.

      • end

        public final void end()
        Ends timing of this event. Method must be invoked after the begin method

      • commit

        public final void commit()
        Writes field values, timestamp and event duration to the Flight Recorder system.

        If the event was started with an invocation of begin, but not ended with an explicit invocation to end, the event will end when the commit method is invoked.

      • isEnabled

        public final 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.
        Returns:
        true if event is enabled, false otherwise

      • shouldCommit

        public final boolean shouldCommit()
        Returns true if event is enabled and if the duration, time elapsed between an invocation to begin and end, is within the threshold for the event, otherwise false is returned. The threshold is determined by taking the minimum threshold for all running recordings.
        Returns:
        true if the event can be committed, false otherwise

      • set

        public final void set​(int index,
                      Object value)
        Sets a field value, only applicable if the event is dynamically defined using EventFactory.

        The supplied index corresponds to the index of the field in ValueDescriptor passed when the event factory was created.

        Parameters:
        index - index of the field passed to EventFactory#create(String, java.util.List, java.util.List)
        value - value to set, may be null
        Throws:
        UnsupportedOperationException - if it's not a dynamically generated event
        IndexOutOfBoundsException - if index is less than 0 or greater or equal than the number of fields for the event
        See Also:
        EventType.getFields(), EventFactory