Chapter 4. Creating a JFR recording with Cryostat

Procedure

1. On the Dashboard panel for your Cryostat web console, select a target JVM from the Target list.

   Note

   Depending on how you configured your target applications, your target JVMs might be using a JMX connection or an agent HTTP connection. For more information about configuring your target applications, see Configuring Java applications.

   Important

   If your target JVM is using an agent HTTP connection, ensure that you set the cryostat.agent.api.writes-enabled property to true when you configured your target application to load the Cryostat agent. Otherwise, the Cryostat agent cannot accept requests to start and stop JFR recordings.

   Figure 4.1. Example of selecting a Target JVM for your Cryostat instance

   

2. Optional: On the Dashboard panel, you can create a target JVM. From the Target list, click Create Target. The Create Custom Target window opens.

   1. In the Connection URL field, enter the URL for your JVM’s Java Management Extension (JMX) endpoint.
   2. Optional: To test if the Connection URL that you specified is valid, click the Click to test sample node image. If there is an issue with the Connection URL, an error message is displayed that provides a description of the issue and guidance to troubleshoot.
   3. Optional: In the Alias field, enter an alias for your JMX Service URL.

   4. Click Create.

      Figure 4.2. Create Custom Target window

      
3. From the navigation menu on the Cryostat web console, click Recordings.

4. Optional: Depending on how you configured your target JVM, an Authentication Required dialog might open on your web console. In the Authentication Required dialog box, enter your Username and Password. To provide your credentials to the target JVM, click Save.

   Figure 4.3. Example of a Cryostat Authentication Required window

   
   Note

   If the selected target JMX has Secure Socket Layer (SSL) certification enabled for JMX connections, you must add its certificate when prompted.

   Cryostat encrypts and stores credentials for a target JVM application in a database that is stored on a persistent volume claim (PVC) on Red Hat OpenShift. See Storing and managing credentials (Using Cryostat to manage a JFR recording).

5. On the Active Recordings tab, click Create.

   Figure 4.4. Example of creating an active recording

   

6. On the Custom Flight Recording tab:

   1. In the Name field, enter the name of the recording you want to create. If you enter a name in an invalid format, the web console displays an error message.

   2. If you want Cryostat to automatically restart an existing recording, select the Restart if recording already exists check box.

      Note

      If you enter a name that already exists but you do not select Restart if recording already exists, Cryostat refuses to create a custom recording when you click the Create button.

   3. In the Duration field, select whether you want this recording to stop after a specified duration or to run continuously without stopping. If you want Cryostat to automatically archive your new JFR recording after the recording stops, click Archive on Stop.
   4. In the Template field, select the template that you want to use for the recording.

   The following example shows continuous JVM monitoring, which you can enable by selecting Continuous from above the Duration field. This setting means that the recording will continue until you manually stop the recording. The example also shows selection of the Profiling template from the Template field. This provides additional JVM information to a JFR recording for troubleshooting purposes.

   Figure 4.5. Example of creating a custom flight recording

   

7. To access more options, click the following expandable hyperlinks:

   • Show advanced options, where you can select additional options for customizing your JFR recording.
   • Show metadata options, where you can add custom labels and metadata to your JFR recording.

8. To create your JFR recording, click Create. The Active Recordings tab opens and lists your JFR recording.

   Your active JFR recording starts collecting data on the target JVM location inside your containerized application. If you specified a fixed duration for your JFR recordings, the target JVM stops the recording when it reaches the fixed duration setting. Otherwise, you must manually stop the recording.

9. Optional: On the Active Recording tab, you can also stop the recording.

   1. Select the checkbox next to the JFR recording’s name. On the toolbar in the Active Recordings tab, the Cryostat web console activates the Stop button.

   2. Click Stop. The JFR adopts the STOPPED status, so it stops monitoring the target JVM. The JFR still shows under the Active Recording tab.

      Figure 4.6. Example of stopping an active recording

      
      Important

      JFR recording data might be lost in the following situations:

      • Target JVM fails
      • Target JVM restarts
      • Target JVM Red Hat OpenShift Deployment is scaled down

      Archive your JFR recordings to ensure you do not lose your JFR recording’s data.

Procedure

1. On the Active Recordings tab, click the Create button. A new window opens on the web console.

   Figure 4.7. Example of creating an active recording

   

2. Click the Snapshot Recording tab.

   Figure 4.8. Example of creating a snapshot recording

   

3. Click Create. The Active Recordings table opens and it lists your JFR snapshot recording. The following example shows a JFR snapshot recording named snapshot-3.

   Figure 4.9. Example of a completed snapshot recording

   
   Note

   You can identify snapshots by the snapshot prefix from the list of active recordings.