Chapter 3. Starting JDK Flight Recorder

Procedure

1. Open the JVM Browser.

   $ JAVA_HOME/bin/jmc

2. Right-click a JVM in JVM Browser view and select Start Flight Recording.

   The Flight Recording Wizard opens.

   Figure 3.1. JMC JFR Wizard

   

   The JDK Flight Recording Wizard has three pages:

   • The first page of the wizard contains general settings for the flight recording including:

     • Name of the recording
     • Path and filename to which the recording is saved
     • Whether the recording is a fixed-time or continuous recording, which event template will be used
     • Description of the recording
   • The second page contains event options for the flight recording. You can configure the level of detail that Garbage Collections, Memory Profiling, and Method Sampling and other events record.
   • The third page contains settings for the event details. You can turn events on or off, enable the recording of stack traces, and alter the time threshold required to record an event.
3. Edit the settings for the recording.

4. Click Finish.

   The wizard exits and the flight recording starts.

Procedure

1. In your custom event type, in the Event class, use the @name annotation to name the custom event. This name displays in the JMC graphical user interface (GUI).

   Example of defining a custom event type name in the Event class

   @Name(“SampleCustomEvent”)
   public class SampleCustomEvent extends Event {...}

2. Define the metadata for your Event class and its attributes, such as name, category, and labels. Labels display event types for a client, such as JMC.

   Note

   Large recording files might cause performance issues, and this might affect how you would like to interact with the files. Make sure you correctly define the number of event recording annotations you need. Defining unnecessary annotations might increase the size of your recording files.

   Example of defining annotations for a sample Event class

   @Name(“SampleCustomEvent”)  1
   @Label("Sample Custom Event")
   @Category("Sample events")
   @Description("Custom Event to demonstrate the Custom Events API")
   @StackTrace(false) 2
   public class SampleCustomEvent extends Event {
   
   
       @Label("Method") 3
       public String method;
   
   
       @Label("Generated Number")
       public int number;
   
   
       @Label("Size")
       @DataAmount 4
       public int size;
   }

   1

   Details annotations, such as @Name, that define metadata for how the custom event displays on the JMC GUI.

   2

   The @StackTrace annotation increases the size of a flight recording. By default, the JFR does not include the stackTrace of the location that was created for the event.

   3

   The @Label annotations define parameters for each method, such as resource methods for HTTP requests.

   4

   The @DataAmount annotation includes an attribute that defines the data amount in bits of bytes. JMC automatically renders the data amount in other units, such as megabytes (MB).

3. Define contextual information in your Event class. This information sets the request handling behavior of your custom event type, so that you configure an event type to collect specific JFR data.

   Example of defining a simple main class and an event loop

   public class Main {
   
   	private static int requestsSent;
   
   	public static void main(String[] args) {
       	// Register the custom event
       	FlightRecorder.register(SampleCustomEvent.class);
       	// Do some work to generate the events
       	while (requestsSent <= 1000) {
           	try {
               	eventLoopBody();
               	Thread.sleep(100);
           	} catch (Exception e) {
               	e.printStackTrace();
           	}
       	}
       }
   
   	private static void eventLoopBody() {
       	// Create and begin the event
       	SampleCustomEvent event = new SampleCustomEvent();
       	event.begin();
       	// Generate some data for the event
       	Random r = new Random();
       	int someData = r.nextInt(1000000);
       	// Set the event fields
       	event.method = "eventLoopBody";
       	event.number = someData;
       	event.size = 4;
       	// End the event
       	event.end();
       	event.commit();
       	requestsSent++;
       }

   In the preceding example, the simple main class registers events, and the event loop populates the event fields and then emits the custom events.

4. Examine an event type in the application of your choice, such as the JMC or the JFR tool.

   Figure 3.2. Example of examining an event type in JMC

   

   A JFR recording can include different event types. You can examine each event type in your application.