diff --git a/README.md b/README.md index c2a9d12f..fb8ce840 100644 --- a/README.md +++ b/README.md @@ -40,16 +40,19 @@ shutdown so that the cause of an unexpected JVM shutdown might be captured for l ## SMART TRIGGERS -`cryostat-agent` supports smart triggers that listen to the values of the MBean Counters and can start recordings based +`cryostat-agent` supports Smart Triggers that listen to the values of the MBean Counters and can start recordings based on a set of constraints specified by the user. -The general form of a smart trigger expression is as follows: +The general form of a Smart Trigger expression is as follows: ``` -[constraint1(&&/||)constraint2...constraintN]~recordingTemplateNameOrLabel +[constraint1(&&/||/==)constraint2...constraintN;durationConstraint]~recordingTemplateNameOrLabel ``` -Either the filename or label XML tag of the `${templateName}.jfc` may be used to specify the event template to use. For example, the JDK distribution ships with a `default.jfc` file containing the top-level `` element. This template may be specified in the Smart Trigger definition as any of `default.jfc`, `default`, or `Continuous`. +Either the filename or label XML tag of the `${templateName}.jfc` may be used to specify the event template to use. For +example, the JDK distribution ships with a `default.jfc` file containing the top-level +`` element. This template may be specified in the Smart Trigger definition as any of +`default.jfc`, `default`, or `Continuous`. An example for listening to CPU Usage and starting a recording using the Profiling template when it exceeds 0.2%: @@ -65,11 +68,13 @@ Continuous template: ``` The first part of the condition before the semicolon is a [Common Expression Language](https://github.com/google/cel-spec) -expression for testing various MBean metrics. The second part after the semicolon references a special variable, -`TargetDuration`, which tracks the length of time that the first part of the condition has tested `true` for. This is -converted to a `java.time.Duration` object and compared to `duration("10s")`, a special construct that is also -converted into a `java.time.Duration` object representing the time threshold before this trigger activates. The -`duration()` construct requires a `String` argument, which may be enclosed in single `'` or double `"` quotation marks. +expression for testing +[various MBean metrics](https://github.com/cryostatio/cryostat-agent/blob/main/src/main/java/io/cryostat/agent/model/MBeanInfo.java) +. The second part after the semicolon references a special variable, `TargetDuration`, which tracks the length of time +that the first part of the condition has tested `true` for. This is converted to a `java.time.Duration` object and +compared to `duration("10s")`, a special construct that is also converted into a `java.time.Duration` object +representing the time threshold before this trigger activates. The `duration()` construct requires a `String` argument, +which may be enclosed in single `'` or double `"` quotation marks. Smart Triggers may define more complex conditions that test multiple metrics: