Featured image for Cryostat (was ContainerJFR) topics.

With the tech preview release of Cryostat 2.1, users can attach metadata or custom labels to JDK flight recordings that monitor containerized Java applications, and can manage those recordings using Cryostat. Recording labels can identify recordings in queries and perform actions on multiple recordings containing the same label. This article shows how to add and edit metadata labels on your JDK flight recordings, including the recordings managed through automated rules.

Add a recording label to a JDK flight recording

Navigate to the Recordings tab on the Cryostat console and select a target JVM from the drop-down menu. Click Create to create a custom flight recording (Figure 1). When creating the flight recording, expand the Show metadata options form section. Click Add Label to add a key-value label pair to the recording. For more details about creating recordings, see the Cryostat guides.

A custom flight recording can be tracked through custom labels.
Figure 1: A custom flight recording can be tracked through custom labels.

The new recording will appear in the Recordings tab with your custom label, along with default labels containing information about the selected recording template, as shown in Figure 2.

The Active Recordings table shows the labels on each recording.
Figure 2: The Active Recordings table shows the labels on each recording.

Edit recording labels for a JDK flight recording

Recording labels can also be edited after recordings have been created or re-uploaded to archives. For instance, it looks like the custom label in our example contains a typo. You can fix it by editing the label.

Click the ellipsis menu beside the recording table entry, then click Edit Metadata. The labels section will appear as a form where you can add, edit, or delete existing labels. Click Save to save your edited labels, as shown in Figure 3.

The value of a label has been edited.
Figure 3: The value of a label has been edited.

The recording labels should now be updated in the Active Recordings table, as shown in Figure 4.

The Active Recordings table shows the updated labels.
Figure 4: The Active Recordings table shows the updated labels.

On the Active Recordings table, click the checkbox next to the recording, then click Archive to archive your recording.

The archived recording also copies the labels from the active recording, as shown in Figure 5. This means you can easily find the archived recordings associated with an active recording by searching for the metadata labels applied to the active recording. You can also add additional labels to any recording uploaded to the Cryostat archives. The labels are preserved for as long as the recording remains in the archives.

Labels are also shown for each recording in the Archived Recordings tab.
Figure 5: Labels are also shown for each recording in the Archived Recordings tab.

Labeling recordings generated with automated rules

Automated rules, introduced in the article How to build automated JFR rules with Cryostat 2.1, simplify the tracking and management of multiple JDK flight recordings. An automated rule automatically applies a metadata label to indicate the name of the automated rule that created that recording. For example, if your automated rule was named my_automated_rule, all recordings generated with that rule will contain the metadata label Rule: my_automated_rule. When these recordings are archived, the labels are preserved to help you easily locate all of your recordings generated by my_automated_rule.

Conclusion

This article has explained how to add and edit recording metadata labels for a single JDK flight recording, or for multiple recordings if they are managed by an automated rule. Automated rules also apply metadata labels to each recording they create.

To search for and operate on recordings using these labels, check out another article in this series, Manage JFR across instances with Cryostat and GraphQL. For more information about Cryostat, visit the project's getting started page. For questions, comments and feedback, feel free to connect with us on GitHub or join our mailing list.

Last updated: September 20, 2023