Skip to content

Trigger queries

Trigger queries can range from simple comparisons ("event status equal to open") to complex series of comparisons with subordinate clauses. The ideal trigger query is specific enough to identify the criteria to initiate an action but no more. Too specific and you risk missing important changes in your environment; too broad and you risk sending misleading notifications.

Note

Zenoss Cloud does not check queries for consistency. For example, a trigger query that specifies "severity equal to critical and severity equal to error" is not marked as an error, even though it is inconsistent.

Event trigger queries

An event trigger query specifies the criteria for initiating actions. Queries can range from simple comparisons ("event status equal to open") to complex series of subordinate clauses.

To facilitate the process of creating queries for your application, experiment with creating triggers in the Zenoss Cloud browser interface, and then use the get multiple triggers resource to display the JSON version of your query.

Clause types

Clauses must contain at least one comparison operation (equals, greaterAndEquals, lessAndEquals, contains, startsWith, endsWith, in) and may be combined with one or more logic operations (not, and, or).

All string comparisons are case-insensitive. For event triggers, the value of the field attribute must be one of the field names that the system uses internally. For a mapping of display names to internal names, see Event field names in trigger queries.

The display names of some operators do not match the internal names used in API queries. The following table maps non-matching display names to internal names.

Display name Internal name
Any or
All and
equal to equals
greater than or equal to greaterAndEquals
less than or equal to lessAndEquals
starts with startsWith
ends with endsWith
one of in

equals

The equals clause supports number, string, and Boolean comparisons.

Example: String comparison

This example compares a string in one field, severity. String comparisons require stringVal, because equality clauses can compare types other than string.

{
  "name": "critical-events",
  "description": "All critical events.",
  "tags": [
    "severity:critical"
  ],
  "type": {
    "event": {
      "query": {
        "clause": {
          "equals": {
            "field": "severity",
            "value": {
              "stringVal": "info"
            }
          }
        }
      }
    }
  }
}

Example: Integer comparison

This example compares an integer and does not use stringVal.

{
  "name": "custom-priority-15",
  "description": "All devices with custom priority 15.",
  "tags": [
    "priority:custom-15"
  ],
  "type": {
    "event": {
      "query": {
        "clause": {
          "equals": {
            "field": "CZ_EVENT_DETAIL-zenoss.device.priority",
            "value": 15
          }
        }
      }
    }
  }
}

greaterAndEquals and lessAndEquals

The greaterAndEquals (greater than or equal to) and lessAndEquals (less than or equal to) clauses support number and string comparisons and work just like the equals clause.

These clauses work for string comparisons when the values to compare are members of an ordered list. The following table shows the eligible fields and the range of possible values, in order.

Field name Least to most significant values
severity default, debug, info, warning, error, critical
CZ_EVENT_DETAIL-zenoss.device.production_state decommissioned, maintenance, test, pre-production, production
CZ_EVENT_DETAIL-zenoss.device.priority trivial, lowest, low, normal, high, highest

If you are using customized versions of these lists, you must perform numeric comparisons.

contains

The contains clause searches for a substring.

If the string specified with value exists anywhere in the specified field, the clause matches. Since contains is always a string comparison, you can specify the value directly, without stringVal.

{
  "name": "test-events",
  "description": "Events with 'test' in their summary.",
  "tags": [
    "summary:test"
  ],
  "type": {
    "event": {
      "query": {
        "clause": {
          "contains": {
            "field": "summary",
            "value": "test"
          }
        }
      }
    }
  }
}

startsWith

The startsWith clause type works just like contains except the string specified with value must be found at the beginning of the specified field .

endsWith

The endsWith clause type works just like contains except the string specified with value must be found at the end of the specified field.

in

The in clause compares the value of a field with an array of values. This clause is only valid with the fields in the following table.

Field name Possible values
status default, open, closed, suppressed
contextType COMPONENT, DEVICE, SERVICE, ORGANIZER
parentContextType COMPONENT, DEVICE, SERVICE, ORGANIZER
CZ_EVENT_DETAIL-zenoss.device.production_state decommissioned, maintenance, test, pre-production, production
CZ_EVENT_DETAIL-zenoss.device.priority trivial, lowest, low, normal, high, highest

The customized versions of these fields are not supported in in clauses.

Example

{
  "name": "test-2",
  "type": {
    "event": {
      "query": {
        "clause": {
          "and": {
            "clauses": [
              {
                "in": {
                  "field": "parentContextType",
                  "values": [
                    {
                      "stringVal": "SERVICE"
                    },
                    {
                      "stringVal": "ORGANIZER"
                    }
                  ]
                }
              }
            ]
          }
        }
      }
    }
  }
}

not

The not clause is used to create the negative versions of the equals, greaterAndEquals, lessAndEquals, and contains clauses.

{
  "name": "important-events",
  "description": "Events that we don't want to ignore.",
  "type": {
    "event": {
      "query": {
        "clause": {
          "not": {
            "clause": {
              "contains": {
                "field": "eventClass",
                "value": "/Ignore"
              }
            }
          }
        }
      }
    }
  }
}

and

The and clause specifies that two or more other clauses must match for the and clause to match. Any type of clause can be nested within an and clause, including other and clauses.

{
  "name": "new-kubernetes-events",
  "description": "New Kubernetes events.",
  "tags": [
    "kubernetes"
  ],
  "type": {
    "event": {
      "query": {
        "clause": {
          "and": {
            "clauses": [
              {
                "equals": {
                  "field": "source-type",
                  "value": {
                    "stringVal": "zenoss.agent.kubernetes"
                  }
                }
              },
              {
                "equals": {
                  "field": "status",
                  "value": {
                    "stringVal": "new"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

or

The or clause type works just like and except that only one of the nested clauses has to match for the or clause to match.

Event field names in trigger queries

The following table maps the event field names displayed in the trigger editor to the names required for trigger queries with an API resource.

Display name Internal name
Severity severity
Status status
Acknowledged acknowledged
Summary summary
Body body
Type type
Name name
Source source
Source Type source-type
CZ Event Class eventClass
CZ Message body
CZ Entity Title contextTitle
CZ Entity ID contextIdentifier
CZ Entity Type contextType
CZ Parent Entity Type parentContextType
CZ Parent Entity Title parentContextTitle
CZ Parent Entity ID parentContextIdentifier
CZ Device Class CZ_EVENT_DETAIL-zenoss.device.device_class
CZ Production State CZ_EVENT_DETAIL-zenoss.device.production_state
CZ Production State (Custom) CZ_EVENT_DETAIL-zenoss.device.production_state
CZ Priority CZ_EVENT_DETAIL-zenoss.device.priority
CZ Priority (Custom) CZ_EVENT_DETAIL-zenoss.device.priority
CZ Collector monitor
CZ Agent agent