Procedure

1. Depending on your operating system, choose one of the following methods to start your JMC console:

   1. On Red Hat Enterprise Linux, navigate to the directory that contains the executable file, and then issue the ./jmc command.

   2. On Microsoft Windows, navigate to the directory that contains the jmc.exe file, and then issue the jmc command.

      Note

      You can also start your JMC application on either operating system by using your system’s file explorer application to navigate to the JDK Mission Control directory, and then double-click the JMC executable file.

2. Navigate to the JVM Browser navigation panel. On this panel, you can view any available JVM connections.
3. Expand your target JVM instance, such as [11.0.13] The JVM Running Mission Control, in the JVM Browser panel. A list of items displays under your target JVM instance.

4. Double-click the JMC Agent item in the navigation panel. A Start JMC Agent window opens in your JMC console:

   Figure 2.1. Start JMC Agent window

   

5. Use the Browse button to add your JMC Agent’s JAR file to the Agent JAR field. The Agent XML field is optional.

   Note

   You do not need to enter a value in the Target JVM field, because JMC automatically adds a value based on your selected target JVM instance.

6. Click the Start button.

   JMC adds the Agent Plugin item under your target JVM instance in the JVM Browser navigation panel. The JMC console automatically opens the Agent Live Config pane.

   Figure 2.2. Agent Live Config pane

   

   You can now configure your JMC Agent or manage interactions between the JMC Agent and your JFR data. After you generate an XML configuration and then upload it to the JMC console, the Agent Live Config pane displays metadata associated with that XML file.

   Figure 2.3. Example of an XML configuration file that has been added to the JMC console

   

Procedure

1. You can create a new preset by clicking Window from the menu bar, and then clicking the JMC Agent Preset Manager menu item. A JMC Agent Configuration Preset Manager wizard opens in your JMC console.

2. Click the Add button to access the Edit Preset Global Configurations window.

   Figure 2.4. Edit Preset Global Configurations window

   

   From this window, you can enter a name for your preset. Optionally, you can enter a class prefix for any events that you want to inject into your target JVM. You can also select the AllowtoString check box and the Allow Converter check box.

3. Click the Next button. An Add or Remove Preset Events window opens. From this window, you can add new events, edit events, or remove events for your preset.

   Figure 2.5. Add or Remove Preset Events

   

4. Follow the wizard’s instructions, where you can complete the following steps:

   1. Edit Event Configurations
   2. Edit a Parameter or Return Value step

   3. Edit a Parameter or Return Value Capturing

      Tip

      You can select any of the available buttons on each wizard step to complete your desired configuration, such as Add, Remove, and so on. You can click the Back button at any stage to edit a previous wizard step.

5. Click the Finish button to return to the Add or Remove Preset Events window.
6. Click Next. A Preview Preset Output window opens.

7. Review the generated XML data before clicking the Finish button:

   Figure 2.6. Preview Preset Output

   
8. Click the Load preset button on the top-right side of the JMC console window, and then upload your preset to the JMC application.

9. On the JMC Agent Configuration Preset Manager window, click the OK button to load your preset into your target JVM. The Agent Live Present panel on your JMC console shows your active agent configuration and any of its injected events. For example:

   Figure 2.7. Example output on the Agent Live Present pane

   

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.