Triggers

A trigger is a statement that specifies an action to be taken when one or more specified
conditions are met for a service, role, role configuration group, or host. The conditions are expressed as a tsquery statement, and the
action to be taken is to change the health for the service, role, role configuration group, or host to either Concerning (yellow) or Bad (red).

Triggers can be created for services, roles, role configuration groups, or hosts. Create a trigger by doing one of the following:

Directly editing the configuration for the service, role (or role configuration group), or host configuration.

Clicking Create Trigger on the drop-down menu for most charts. Note that the Create Trigger command is not available on the drop-down menu for charts
where no context (role, service, and so on) is defined, such as on the Home > Status tab.
Important: Because triggers are a new and evolving feature, backward
compatibility between releases is not guaranteed at this time.

The Structure of Triggers

A trigger is defined by a JSON formatted string that includes four parts:

Name

Expression

Stream threshold

Whether or not the trigger should be enabled

Each of the four parts of a trigger is described in the following sections.

Name (required)

A trigger's name must be unique in the context for which the trigger is defined. That is, there cannot be two triggers for the same service or role with the same name. Different services
or different roles can have triggers with the same name.

Expression (required)

A trigger expression takes the form:

IF (CONDITIONS) DO HEALTH_ACTION

When the conditions of the trigger are met, the trigger is considered to be firing. A condition is any valid tsquery statement. In most cases conditions employ stream filters to filter
out streams below or above a certain threshold. For example, the following tsquery can be used to retrieve the streams for DataNodes with more than 500 open file descriptors:

SELECT fd_open WHERE roleType=DataNode AND last(fd_open) > 500

The stream filter used here, last(fd_open) > 50, is composed of four parts:

A scalar producing function "last" that takes a stream and returns its last data point

A metric to operate on

A comparator

A scalar value

Other scalar producing functions are available, like min or max, and they can be combined to create arbitrarily complex
expressions:

Conditions can be combined using the logical operators AND and OR. For example, here is a trigger expression with two
conditions:

IF ((SELECT fd_open WHERE roleType=DataNode AND last(fd_open) > 500) OR (SELECT fd_open WHERE roleType=NameNode AND last(fd_open) > 500)) DO health:bad

A condition is met if it returns more than the number of streams specified by the streamThreshold (see below). A trigger fires if the logical evaluation of
all of its conditions results in a met condition. When a trigger fires, two actions can be taken: health:concerning or health:bad. These
actions change the health of the entity on which the trigger is defined.

Stream Threshold (optional)

The stream threshold determines the number of streams that need to be returned by the tsquery before the condition is met. The default is 0; that is, if the tsquery returns any results
the condition will be met. For example if the stream threshold is set to 10 and the condition is SELECT fd_open WHERE roleType=DataNode AND last(fd_open) > 500 the
condition will be considered met only if there are at least 10 DataNodes that have more than 500 file descriptor opened, so at least 10 streams were returned by the tsquery.

Enabled (optional)

Whether the trigger is enabled. The default is true, (enabled).

Trigger Example

The following is a JSON formatted trigger that fires if there are more than 10 DataNodes with more than 500 file descriptors opened:

Creating a Trigger Using the Expression Editor

The Create New Trigger screen allows you to use a graphical editor to build the JSON string that defines a trigger. You can use the expression editor
section to build the tsquery statement, or you can edit the tsquery statement manually. Triggers use the tsquery Language to create
trigger expressions.

To create a trigger using the expression editor:

Go to a service, role, role configuration group, or host configuration page and click the Create Trigger button next to the Health Test section.

The Create New Trigger screen displays.

As you build the trigger, the actual query text displays to the right, along with a preview of a chart returned by the query.

Select the function to use in your expression, either Last, Min, or Max.

Select the metric by typing its name in the Metric field. A list of available metrics displays as you type.

Select the operator, either >, >=, =, <, or <=.

Enter the value to use for the comparison in the Value field.

(Optional) Click the + icon to add additional expressions. Additional expressions are added to the query using the logical operator AND.

(Optional) Create a predicate for the query. Under Attribute Conditions, click the
+ icon to add an attribute condition.

A set of fields displays that you use to build an expression for the predicate.

Type the attribute name in the Attribute field. A list of attributes displays as you type.

Select the operator, either = or RLIKE.

Enter the value for the comparison in the Value field.

(Optional) Click the + icon to add additional expressions. Additional expressions are added to the predicate using the logical operator AND.

Select an Action from the drop-down menu to define the action taken when the trigger fires:

Mark as bad (red)

Mark as concerning (yellow)

Enter a value for the Stream Threshold. Leave the value set to 0 to include all streams; enter an integer to set the
number of streams required to meet the condition. See Stream Threshold.

Select Enabled to enable the trigger. If you disable the trigger, it does not run.

(Optional) Select Suppressed. A suppressed trigger still runs but does not impact the health display of the owning entity.

Verify your expression:

In the area to the right of the expression builder, in the Preview section, the expression you have built displays. A chart also displays the result of
the query. Click Show Filtered Streams to see all streams. Click Hide Filtered Streams to hide streams that do not meet the Stream
Threshold (optional).

You can edit your trigger using the fields in the expression builder, or you can click the Edit Manually link to display a text box in which you can manually edit
the trigger. Click Use Editor to return to the expression builder.
Important: If you select Edit Manually, changes you make manually do not appear in the expression builder
when you click Use Editor.

Click Create Trigger to save your trigger.

Editing, Deleting, Suppressing, or Deleting a Trigger

Go to the service, role, role configuration group, or host configuration page where the trigger was created. (For example: select Clusters > HDFS.)

In the Health Tests section, click the trigger name. (You may need to click a Show ... link to expand the list of
triggers.)

A page displays showing the query and chart for the trigger. Click Show Filtered Streams to see all streams. Click Hide Filtered Streams to hide streams that do not meet the Stream
Threshold (optional).

Click the Actions drop-down menu and select one of the following actions:

Edit Trigger

A page opens where you can edit the query. Click Save Trigger to save your changes.

If this documentation includes code, including but not limited to, code examples, Cloudera makes this available to you under the terms of the Apache License, Version 2.0, including any required
notices. A copy of the Apache License Version 2.0 can be found here.