Chapter 4. Creating a JFR recording with Cryostat
Chapter 4. Creating a JFR recording with Cryostat With Cryostat, you can create a JDK Flight Recorder (JFR) recording that monitors the performance of your JVM in your containerized application. Additionally, you can take a snapshot of an active JFR recording to capture any collected data, up to a specific point in time, for your target JVM application. 4.1. Creating a JFR recording in the Cryostat web console You can create a JFR recording that monitors the performance of your JVM located in your containerized application. After you create a JFR recording, you can start the JFR to capture real-time data for your JVM, such as heap and non-heap memory usage. Prerequisites Installed Cryostat 3.0 on Red Hat OpenShift by using the OperatorHub option. Created a Cryostat instance in your Red Hat OpenShift project. Logged in to your Cryostat web console. You can retrieve your Cryostat application's URL by using the Red Hat OpenShift web console. Procedure 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 Optional: On the Dashboard panel, you can create a target JVM. From the Target list, click Create Target . The Create Custom Target window opens. In the Connection URL field, enter the URL for your JVM's Java Management Extension (JMX) endpoint. 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. Optional: In the Alias field, enter an alias for your JMX Service URL. Click Create . Figure 4.2. Create Custom Target window From the navigation menu on the Cryostat web console, click Recordings . 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). On the Active Recordings tab, click Create . Figure 4.4. Example of creating an active recording On the Custom Flight Recording tab: 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. 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. 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 . 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 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. 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. Optional: On the Active Recording tab, you can also stop the recording. Select the checkbox to the JFR recording's name. On the toolbar in the Active Recordings tab, the Cryostat web console activates the Stop button. 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. Additional resources See Uploading an SSL certificate (Using Cryostat to manage a JFR recording). See Archiving JDK Flight Recorder (JFR) recordings (Using Cryostat to manage a JFR recording). 4.2. Creating snapshots from an active recording You can take a snapshot of an active JFR recording to capture any collected data, up to a specific point in time, for your target JVM application. A snapshot is like a checkpoint marker that has a start point and an end point for a given time segment in a running JFR recording. A snapshot gets stored in the memory of a target JVM application. This differs from an archive in that Cryostat stores an archive on a cloud storage disk, which is a more permanent solution for storing a JFR recording's data. You can take snapshots of recordings if you want to experiment with different configuration changes among active JFR recordings. When you create a snapshot for your JFR recording, Cryostat creates a new target JVM named snapshot - <snapshot_number> , where <snapshot_number> is the number that Cryostat automatically assigns to your snapshot. A target JVM recognizes a snapshot as an active recording. Cryostat sets any JFR snapshots in the STOPPED state, which means that the JFR snapshot does not record new data to the target JVM. Depending on the JFR configuration, active JFR recordings can continue to monitor the target JVM regardless of the number of snapshots taken. Note For a JFR recording that you set for continuous monitoring of a target JVM application, ensure that you create archived recordings to avoid losing JFR recording data. If you choose to take regular snapshots to store your JFR recording data, the target JVM application might free some of its data storage space by replacing older recording data with newer recording data. Prerequisites Entered your authentication details for your Cryostat instance. Created a target JVM recording and entered your authenticated details to access the Recordings menu. See Creating a JDK Flight Recorder (JFR) recording (Creating a JFR recording with Cryostat). Procedure 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 Click the Snapshot Recording tab. Figure 4.8. Example of creating a snapshot recording 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. steps To archive your JFR snapshot recording, see Archiving JDK Flight Recorder (JFR) recordings . 4.3. Labels for JFR recordings When you create a JDK Flight Recorder (JFR) recording on Cryostat 3.0, you can add metadata to the recording by specifying a series of key-value label pairs. Additionally, you can attach custom labels to JFR recordings that are inside a target JVM, so that you can easily identify and better manage your JFR recordings. The following list details some common recording label use cases: Attach metadata to your JFR recording. Perform batch operations on recordings that contain identical labels. Use labels when running queries on recordings. You can use Cryostat to create a JFR recording that monitors the performance of your JVM in your containerized application. Additionally, you can take a snapshot of an active JFR recording to capture any collected data, up to a specific point in time, for your target JVM application. 4.3.1. Adding labels to JFR recordings When you create a JFR recording on Cryostat 3.0, you can use labels to add metadata that contain key-value label pairs to the recording. Cryostat applies default recording labels to a created JFR recording. These default labels capture information about the event template that Cryostat used to create the JFR recording. You can add custom labels to your JFR recording so that you can run specific queries that meet your needs, such as identifying specific JFR recordings or performing batch operations on recordings with the same applied labels. Prerequisites Logged in to your Cryostat web console. Created or selected a target JVM for your Cryostat instance. Procedure From your Cryostat web console, click Recordings . Under the Active Recordings tab, click Create . On the Custom Flight Recording tab, expand Show metadata options . Note On the Custom Flight Recording tab, you must complete any mandatory field that is marked with an asterisk. Click Add label . Figure 4.10. The Add Label button that is displayed under the Custom Flight Recording tab Enter values in the provided Key and Value fields. For example, if you want to file an issue with the recordings, you could enter the reason in the Key field and then enter the issue type in the Value field. Click Create to create your JFR recording. Your recording is then shown under the Active Recordings tab along with any specified recording labels and custom labels. Tip You can access archived JFR recordings from the Archives menu. See Uploading a JFR recording to Cryostat archives location (Using Cryostat to manage a JFR recording). Example The following example shows two default recording labels, template.name: Profiling and template.type: TARGET , and one custom label, reason:service-outage . Figure 4.11. Example of an active recording with defined recording labels and a custom label 4.3.2. Editing a label for your JFR recording On the Cryostat web console, you can navigate to the Recordings menu and then edit a label and its metadata for your JFR recording. You can also edit the label and metadata for a JFR recording that you uploaded to archives. Prerequisites Logged in to your Cryostat web console. Created a JFR recording and attach labels to this recording. Procedure On your Cryostat web console, click the Recording menu. From the Active Recordings tab, locate your JFR recording, and then select the checkbox to it. Click Edit Labels . An Edit Recording Label pane opens in your Cryostat web console, which you can use to add, edit, or delete labels for your JFR recording. Tip You can select multiple JFR recordings by selecting the checkbox that is to each recording. Click the Edit Labels button if you want to bulk edit recordings that contain the same labels or add new identical labels to multiple recordings. Optional : You can perform any of the following actions from the Edit Recording Labels pane: Click Add to create a label. Delete a label by clicking the X to the label. Edit a label by modifying any content in a field. After you edit content, a green tick is shown in the field to indicate an edit. Click Save . Optional : You can archive your JFR recordings along with their labels by completing the following steps: Select the checkbox to the recording's name. Click the Archive button. You can locate your recording under the Archived Recordings tab. By archiving your recording with its labels, you can enhance your search capabilities when you want to locate the recording at a later stage. You can also add additional labels to any recording that you uploaded to the Cryostat archives. Note Cryostat preserves any labels with the recording for the lifetime of the archived recording. Verification From the Active Recordings tab, check that your changes display under the Labels section for your recording. Additional resources Archiving JDK Flight Recorder (JFR) recordings (Using Cryostat to manage a JFR recording) Revised on 2025-01-10 16:01:12 UTC