Chapter 3. JMC Agent Plugin

Procedure

1. From your Cryostat web console, go to the Events menu. If the JMC Agent was successfully added to your Cryostat instance then a Probe Templates pane opens under the Event Templates pane.

   Figure 3.1. The Probe Templates tab on the Cryostat web console

   
   Note

   An Authentication Required dialog box might open on your web console. If prompted, enter your Username and Password in the Authentication Required dialog box, and click Save to provide your JMX credentials to the target JVM.

2. Use your preferred text editor to create an XML configuration file. Populate the file with JFR event information, such as what events Cryostat must perform on the application.

   The following example shows a custom probe template XML file that contains JFR event information. When this file is uploaded to Cryostat, Cryostat can add a custom JFR event, called Cryostat Agent Plugin Demo Event, to an application. Cryostat starts the JFR event when the retrieveEventProbes method of the JMC Agent is called.

   <jfragent>
       <!-- Global configuration options -->
       <config>
      	 <classprefix>__JFREvent</classprefix>
      	 <allowtostring>true</allowtostring>\
      	 <allowconverter>true</allowconverter>
       </config>
      	 <events>
      		 <event id="cryostat.demo.jfr.event9">
          		 <label>Cryostat Agent Plugin Demo Event</label>
          		 <description>Event for the agent plugin demo</description>
          		 <path>io/cryostat/demo/events</path>
          		 <stacktrace>true</stacktrace>
          		 <class>io.cryostat.core.agent.AgentJMXHelper</class>
          		 <method>
              		 <name>retrieveEventProbes</name>
      		 <descriptor>()Ljava/lang/String;</descriptor>
          		 </method>
           	<location>WRAP</location>
       	</event>
   	</events>
   </jfragent>

3. Click the Upload button to add a custom event template to Cryostat. A Create Custom Probe Template opens on your Cryostat web console.

   Figure 3.2. The Create Custom Probe Template window on the Cryostat web console

   
   Tip

   Click the Clear button if you want to remove the uploaded file from this Template XML field.

4. Click the Browse button to locate your XML file.
5. After you upload the file, click Submit. Your custom probe template file opens in the Probe Templates table.
6. Click the overflow menu that is next to your probe template.
7. Click Insert Probes. The probes display in the table under the Probe Templates tab and the table under the Live Configuration tab.
8. Optional: Go to the Live Configuration tab, where you can view information, such as Name, Class, and so on, for each active probe.
9. Optional: From the Live Configuration tab, you can click Remove All Probes to delete probes that are listed in the table.

Verification

1. From the Events menu, click the Event Types tab.
2. Check that the named JFR event from your XML configuration is listed in the table. For the example used in this procedure, Cryostat Agent Plugin Demo Event displays in the table.