Ce contenu n'est pas disponible dans la langue sélectionnée.
Chapter 2. Configuration of a custom trigger for a dynamic recording
When you configure your target application to load the Cryostat agent, you can define one or more custom triggers that are then passed as arguments to the agent.
For more information about configuring a target application to load the Cryostat agent, see Configuring Java applications.
2.1. Options for defining a custom trigger
You can define a custom trigger in any of the following ways:
- Appending a custom trigger to the Cryostat agent’s JAR file path
The following example shows how to append a simple custom trigger to the Cryostat agent’s JAR file path:
JAVA_OPTS="-javaagent:/deployments/app/cryostat-agent-shaded.jar=\"[ProcessCpuLoad > 0.2 ; TargetDuration > duration('30s')]~profile\""The preceding example trigger instructs the agent to start a JFR recording if the
ProcessCpuLoadmetric has a value greater than 0.2 for a duration of more than 30 seconds: This example also instructs the agent to use theprofileevent template for the JFR recording.- Using a JVM system property flag
The following example shows how to specify a simple custom trigger by using a JVM system property flag:
-Dcryostat.agent.smart-trigger.definitions="[ProcessCpuLoad > 0.2 ; TargetDuration > duration(\"30s\")]~profile"
This example uses the same custom trigger criteria as the preceding example.
- Using an environment variable
The following example shows how to specify a simple custom trigger by using an environment variable:
- name: CRYOSTAT_AGENT_SMART_TRIGGER_DEFINITIONS value: "[ProcessCpuLoad > 0.2 ; TargetDuration > duration(\"30s\")]~profile"
This example uses the same custom trigger criteria as the preceding examples.
2.2. Common Expression Language
You can use Common Expression Language (CEL) to define a custom trigger condition. CEL is a free-form expression syntax that provides great flexibility in defining rules and constraints for evaluating data. For example, you can use CEL to create relational statements for evaluating if any combination of MBean counter types have current values greater than, equal to, or less than specified configurable values. You can also include any combination of AND (&&) or OR (||) logic statements between different MBean counter types that are part of the same trigger condition.
For more information about CEL, see the CEL language specification.
2.3. General syntax rules for custom triggers
Consider the following syntax guidelines for defining custom triggers:
- A custom trigger definition must consist of both an expression that defines the overall trigger condition and the name of an event template that is used for the JFR recording.
-
The entire trigger expression must be enclosed in square brackets (for example,
[ProcessCpuLoad > 0.2 ; TargetDuration < duration("30s")]). - For readability, you may use white space in a trigger expression as shown in the preceding example, but this is not a requirement.
-
The name of the event template must be defined after the trigger expression and preceded by a tilde (
~) character (for example,~profile). -
A trigger expression can consist of one or more constraints and a target duration. The set of constraints and target duration must be separated by a semicolon (
;) character. -
Each constraint must include: the name of an MBean counter; a relational operator such as
>(greater than),=(equal to),<(less than), and so on; and a specified value. The type of relational operator and value that you can specify depends on the associated MBean counter type (for example,ProcessCpuLoad > 0.2). Constraints can be grouped together by using logical operators such as
&&(AND),||(OR), or!(NOT) logic. For readability and clarity around the order of operations and operator precedence, grouped constraints may be enclosed in round brackets, but this is not a requirement. For example:[(MetricA > value1 && MetricB < value2) || MetricC == 'stringvalue' ; TargetDuration > duration("30s")]
- The name of each MBean counter that is specified as part of a custom trigger must follow precise syntax rules in terms of spelling and capitalization. For a full list of the MBean metrics that you can specify, see MBean counter types.
- Only one target duration can be defined for a custom trigger. The target duration is applied to the entire trigger expression that is enclosed within the square brackets.
-
A target duration can be expressed in terms of seconds, minutes, or hours. For example,
30smeans 30 seconds,5mmeans five minutes,2hmeans two hours, and so on. - A target duration is optional. If a target duration is not specified, triggering will occur immediately once the trigger conditions are met.
Multiple custom trigger definitions can be specified together, each of which relates to a separate JFR recording. Different custom trigger definitions must be separated by a comma (
,) character. For example:[ProcessCpuLoad>0.2]~profile,[ThreadCount>30]~Continuous
