Trigger queries

Triggers often include queries, which can range from simple comparisons ("event status equal to open") to complex series of comparisons with subordinate (child) clauses.

A trigger query consists of one set of comparisons, and optionally, additional sets of child comparisons. For each set of comparisons, you specify whether the set is satisfied when all or any of its comparisons are satisfied.

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 and may be combined with one or more logic operations (not, and, or). Comparison operations vary by trigger type and field.

Event trigger comparisons: equals, greaterAndEquals, lessAndEquals, contains, startsWith, endsWith, in
Metric and anomaly trigger comparisons: equals, contains, startsWith, endsWith

All string comparisons are case-insensitive. The value of the field attribute must be one of the names that the system uses internally. For a mapping of display names to internal names, see the following tables:

Field names in anomaly trigger queries
Field names in event trigger queries
Field names in metric trigger queries

The display names of some operations 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 may be used in 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.

Field names in anomaly trigger queries

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

Display name	Internal name
Metric Name	`metricName`
Metric ID	`metricId`
Entity ID	`entity.id`
Entity Title	`entity.name`
Device Name	`entity.device`
Device Class	`entity._zorgs_device_class`
Group	`entity._zorgs_groups`
System	`entity._zorgs_systems`
Location	`entity._zorgs_location`
Source Type	`entity.source-type`
Production State	`entity.prod_state`

Field names in event 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`
CZ Event Class	`eventClass`
CZ Message	`message`
CZ Entity Type	`contextType`
CZ Parent Entity Type	`parentContextType`
CZ Parent Entity Title	`parentContextTitle`
CZ Parent Entity ID	`parentContextIdentifier`
CZ Production State	`CZ_EVENT_DETAIL-zenoss.device.production_state`
CZ Production State (Custom)	`CZ_EVENT_DETAIL-zenoss.device.production_state.custom`
CZ Priority	`CZ_EVENT_DETAIL-zenoss.device.priority`
CZ Priority (Custom)	`CZ_EVENT_DETAIL-zenoss.device.priority.custom`
CZ Collector	`monitor`
CZ Agent	`agent`
Entity ID	`entity.id`
Entity Title	`entity.name`
Device Name	`entity.device`
Device Class	`entity._zorgs_device_class`
Group	`entity._zorgs_groups`
System	`entity._zorgs_systems`
Location	`entity._zorgs_location`
Source Type	`entity.source-type`

Field names in metric trigger queries

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

Display name	Internal name
Metric ID	`metricId`
Entity ID	`entity.id`
Entity Title	`entity.name`
Device Name	`entity.device`
Device Class	`entity._zorgs_device_class`
Group	`entity._zorgs_groups`
System	`entity._zorgs_systems`
Location	`entity._zorgs_location`
Source Type	`entity.source-type`
Production State	`entity.prod_state`