Chapter 2. Creating definitions
When creating an automated rule definition, you can configure numerous options. Cryostat uses an automated rule to apply rules to any JVM targets that match regular expressions defined in the matchExpression
string expression. You can apply Red Hat OpenShift labels or annotations as criteria for a matchExpression
definition.
After you specify a rule definition for your automated rule, you do not need to re-add or restart matching targets. If you have defined matching targets, you can immediately activate a rule definition.
If you want to reuse an existing automated rule definition, you can upload your definition in JSON format to Cryostat.
From Cryostat 3.0 onward, you must use Common Expression Language (CEL) syntax when defining match expressions in automated rules. In previous releases, you could use JavaScript syntax to define match expressions.
2.1. Enabling or disabling existing automated rules
You can enable or disable existing automated rules by using a toggle switch on the Cryostat web console.
Prerequisites
- Logged in to the Cryostat web console.
- Created an automated rule.
Procedure
From the Cryostat web console, click Automated Rules. The Automated Rules window opens and displays your automated rule in a table.
Figure 2.1. Example of match expression output from completing an automated rule
In the Enabled column, view the Enabled status of the listed automated rules. Depending on the status, choose one of the following actions:
-
To enable the automated rule, click the toggle switch to
On
. Cryostat immediately evaluates each application that you defined in the automated rule against its match expression. If a match expression applies to an application, Cryostat starts a JFR recording that monitors the performance of the application. -
To disable the automated rule, click the toggle switch to
Off
. The Disable your Automated Rule window opens. To disable the selected automated rule, click Disable. If you want to also stop any active recordings that were created by the selected rule, select Clean then click Disable.
-
To enable the automated rule, click the toggle switch to
2.2. Creating an automated rule definition
While creating an automated rule on the Cryostat web console, you can specify the match expression that Cryostat uses to select all the applications. Then, Cryostat starts a new recording by using a JFR event template that was defined by the rule.
If you previously created an automated rule and Cryostat identifies a new target application, Cryostat tests if the new application instance matches the expression and starts a new recording by using the associated event template.
Prerequisites
- Created a Cryostat instance in your Red Hat OpenShift project.
- Created a Java application.
- Installed Cryostat 3.0 on Red Hat OpenShift by using the OperatorHub option.
- Logged in to your Cryostat web console.
Procedure
- In the navigation menu on the Cryostat web console, click Automated Rules. The Automated Rules window opens.
Click Create. A Create window opens.
Figure 2.2. The Create window (Graph View) for an automated rule
- Enter a rule name in the Name field.
In the Match Expression field, specify the match expression details.
NoteSelect the question mark icon to view suggested syntax in a Match Expression Hint snippet.
In the Match Expression Visualizer panel, the Graph View option highlights the target JVMs that are matched. Unmatched target JVMs are greyed out.
Optional: In the Match Expression Visualizer panel, you can also click List View, which displays the matched target JVMs as expandable rows.
Figure 2.3. The Create window (List View) for an automated rule
- From the Template list, select an event template.
To create your automated rule, click Create. The Automated Rules window opens and displays your automated rule in a table.
Figure 2.4. Example of match expression output from completing an automated rule
If a match expression applies to an application, Cryostat starts a JFR recording that monitors the performance of the application.
- Optional: You can download an automated rule by clicking Download from the automated rule’s overflow menu. You can then configure a rule definition in your preferred text editor or make additional copies of the file on your local file system.
2.3. Cryostat Match Expression Visualizer panel
You can use the Match Expression Visualizer panel on the web console to view information in a JSON structure for your selected target JVM application. You can choose to display the information in a Graph View or a List View mode. The Graph View highlights the target JVMs that are matched. Unmatched target JVMs are greyed out. The List View displays the matched target JVM as expandable rows.
To view details about a matched target JVM, select the target JVM that is highlighted. In the window that appears, information specific to the metadata for your application is shown in the Details tab. You can use any of this information as syntax in your match expression. A match expression is a rule definition parameter that you can specify for your automated rule.
After you specify match expressions and created the automated rule, Cryostat immediately evaluates each application that you defined in the automated rule against its match expression. If a match expression applies to an application, Cryostat starts a JFR recording that monitors the performance of the application.
2.4. Uploading an automated rule in JSON
You can reuse an existing automated rule by uploading it to the Cryostat web console, so that you can quickly start monitoring a running Java application.
Prerequisites
- Created a Cryostat instance in your project. See Installing Cryostat on OpenShift using an operator (Installing Cryostat).
- Created a Java application.
- Created an automated rules file in JSON format.
- Logged in to your Cryostat web console.
Procedure
- In the navigation menu on the Cryostat web console, click Automated Rules. The Automated Rules window opens.
Click the file upload icon, which is located beside the Create button.
Figure 2.5. The automated rules upload button
The Upload Automated Rules window opens.
Click Upload and locate your automated rules files on your local system. You can upload one or more files to Cryostat. Alternatively, you can drag files from your file explorer tool and drop them into the JSON File field on your web console.
ImportantThe Upload Automated Rules function only accepts files in JSON format.
Figure 2.6. A window prompt where you can upload JSON files that contains your automated rules configuration
Optional: If you need to remove a file from the Upload Automated Rules function, click the X icon on the selected file.
Figure 2.7. Example of uploaded JSON files
- Click Submit.
2.5. Metadata labels
When you create an automated rule to enable JFR to continuously monitor a running target application, the automated rule automatically generates a metadata label. This metadata label indicates the name of the automated rule that generates the JFR recording. After you archive the recording, you can run a query on the metadata label to locate the automated rule that generated the recording.
Cryostat preserves metadata labels for the automated rule in line with the lifetime of the archived recording.