From ac49320e5623353c894916161e81017aac199f30 Mon Sep 17 00:00:00 2001 From: Andrew Azores Date: Tue, 11 Jun 2024 09:35:29 -0400 Subject: [PATCH] docs(guides): update doc for automated rule creation (#193) * expression is CEL * target includes jvmId * spacing * formatting * capitalization * link other guides * correct quotation marks * correct regex syntax * correct examples for labels/annotations maps and optional keys * correct example expr --- .../_subsections/create-an-automated-rule.md | 23 ++++++++++--------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/guides/_subsections/create-an-automated-rule.md b/guides/_subsections/create-an-automated-rule.md index 9be9893..3388052 100644 --- a/guides/_subsections/create-an-automated-rule.md +++ b/guides/_subsections/create-an-automated-rule.md @@ -58,11 +58,12 @@ Previously, if we wanted to enable always-on `Continuous` monitoring using **JDK
Create your Match Expression

- The Match Expression in a rule definition is a Java-like snippet of code that Cryostat interprets and uses to determine if a rule should be applied to any given target. Match Expressions should thus evaluate to a boolean value. The simplest Match Expressions would be the booleans true or false; if we use true, the rule will apply to every target. The Expression has a target object in global scope, with the following form in JSON notation: + The Match Expression in a rule definition is a Common Expression Language expression that Cryostat interprets and uses to determine if a rule should be applied to any given target. Match Expressions should thus evaluate to a boolean value. The simplest Match Expressions would be the booleans true or false; if we use true, the rule will apply to every target. The Expression has a target object in global scope, with the following form in JSON notation:

{% highlight json %} { + "jvmId": "abcd1234", "alias": "myAppAlias", "connectUrl": "service:jmx:rmi:///jndi/rmi://cryostat:9091/jmxrmi", "labels": { @@ -82,28 +83,28 @@ Previously, if we wanted to enable always-on `Continuous` monitoring using **JDK {% endhighlight %}

- The Alias, connectUrl, labels, annotations.platform, and annotations.cryostat properties are all guaranteed to be present on the target object. alias and connectUrl will be non-empty strings. The labels and platform annotations may be empty—in OpenShift or Kubernetes, these are populated from the labels and annotations applied to the target’s pod, if any. The Cryostat annotations map will vary per platform, but on OpenShift or Kubernetes you can expect the HOST, PORT, NAMESPACE, and POD_NAME keys to be present and non-empty. + The alias, connectUrl, labels, annotations.platform, and annotations.cryostat properties are all guaranteed to be present on the target object. alias and connectUrl will be non-empty strings. The jvmId is a hash string computed by Cryostat after it successfully connects to a target JVM and is used to uniquely identify that JVM instance - it will be empty if Cryostat has not yet connected to that target (for example, if its SSL/TLS certificate is not trusted or if Cryostat is missing the required credentials) The labels and platform annotations may be empty — in OpenShift or Kubernetes, these are populated from the labels and annotations applied to the target’s pod, if any. The Cryostat annotations map will vary per platform, but on OpenShift or Kubernetes you can expect the HOST, PORT, NAMESPACE, and POD_NAME keys to be present and non-empty. Take care to use the `has` or `in` operators when dealing with the labels and annotations map structures where specific keys may not exist. Here are some examples of Match Expressions:

{% highlight bash %} -target.alias == ’com.example.MainClass’ +target.alias == 'com.example.MainClass' -target.alias == ’myAlias’ +target.alias == 'myAlias' -target.labels[‘com.example/service’] == ’customer-login’ +'com.example/service' in target.labels && target.labels[‘com.example/service’] == 'customer-login' -target.labels[‘com.example/service’] != ’customer-login’ +'com.example/service' in target.labels && target.labels[‘com.example/service’] != 'customer-login' -target.annotations.cryostat.PORT > 3000 +has(target.annotations.cryostat.PORT) && target.annotations.cryostat.PORT > 3000 -target.annotations.cryostat.PORT > 3000 && target.annotations.platform[‘io.kubernetes/annotation’] == ‘enabled’ +has(target.annotations.cryostat.PORT) && 'io.kubernetes/annotation' in target.annotations.platform && target.annotations.cryostat.PORT > 3000 && target.annotations.platform['io.kubernetes/annotation'] == 'enabled' -!!target.annotations.platform[‘io.kubernetes/annotation’] +!('io.kubernetes/annotation' in target.annotations.platform) -/^customer-login[0-9]\*$/.test(target.alias) +target.alias.matches("^customer-login[0-9]\*$") {% endhighlight %}
@@ -177,7 +178,7 @@ We can define a rule that applies to any `target` application that has platform- { "name": "k8sMonitoring", "description": "Enable the Demo template on any target with the jfrMonitoring=true annotation", - "matchExpression": "target.annotations.platform[‘jfrMonitoring’]==’enabled’", + "matchExpression": "'jfrMonitoring' in target.annotations.platform && target.annotations.platform['jfrMonitoring']=='enabled'", "eventSpecifier": "template=Demo,type=CUSTOM", "archivalPeriodSeconds": 300, "preservedArchives": 12