[FIXED] Where are built-in JFR (Java Flight Recorder) events documented?

Issue

Working with JDK 11, if you look at the summary of the JRF recording, you can see that there are 140 different events. Some of them may have not occurred, which is clearly visible in the output:

$ jfr summary /c/dev/jfrec/ddos.jfr

 Version: 2.0
 Chunks: 1
 Start: 2020-10-31 19:39:36 (UTC)
 Duration: 54 s

 Event Type                              Count  Size (bytes)
=============================================================
 jdk.JavaMonitorWait                      2727         79342
 jdk.NativeMethodSample                   2590         40722
 jdk.ThreadPark                           2125         89947
 ...
 jdk.GCHeapConfiguration                     1            30
 jdk.YoungGenerationConfiguration            1            21
 jdk.JavaMonitorInflate                      0             0
 jdk.ReservedStackActivation                 0             0

All of them have names like they were Java classes in package jdk.

On the other hand if I want to implement my own custom JFR event I have to extend the jdk.jfr.Event class, so I suppose that all jdk.* events extend the jdk.jfr.Event too.

Inside the official Java SE Javadocs (https://docs.oracle.com/en/java/javase/11/docs/api/index.html) the jdk.jfr.Event is documented but the jdk.* classes are not.

If not inside official Java SE platform Javadocs, then where is the official documentation of built-in JFR event classes placed?

Solution

The events and their field layout depends on the JDK version.

Even though the event names look like package names, most of the events in the JDK are not implemented using a Java class. The prefix "jdk." is only used to differentiate them from user defined events.

If you want to see what a particular JDK supports you can use the 'jfr' tool to look at the metadata.

JDK 11-16:

$ java -XX:StartFlightRecording:filename=m.jfr -version
$ jfr metadata m.jfr.

JDK 17, and later:

$ jfr metadata 

The output will be in Java syntax, even though the actual event is defined by other means.

@Name("jdk.CPUInformation")
@Category({"Operating System", "Processor"})
@Label("CPU Information")
class CPUInformation extends jdk.jfr.Event {
  @Label("Start Time")
  @Timestamp("TICKS")
  long startTime;

  @Label("Type")
  String cpu;

  @Label("Description")
  String description;

  @Unsigned
  @Label("Sockets")
  int sockets;

  @Unsigned
  @Label("Cores")
  int cores;

  @Unsigned
  @Label("Hardware Threads")
  int hwThreads;
}

(If you are interested in the implementation, there are native events that are generated C++ classes from an XML description[1]. Events in java.base / jdk.internal.event [2] lacks metadata, but are added using mirror events located in jdk.jfr / jdk.jfr.events [3], where you also can find some events implemented in Java as well).

[1]https://github.com/openjdk/jdk/blob/master/src/hotspot/share/jfr/metadata/metadata.xml

[2] https://github.com/openjdk/jdk/tree/master/src/java.base/share/classes/jdk/internal/event

[3] https://github.com/openjdk/jdk/tree/master/src/jdk.jfr/share/classes/jdk/jfr/events

Answered By - Kire Haglin
Answer Checked By - Marilyn (JavaFixing Volunteer)