Build a scope filter query
The APEX AIOps Incident Management features which include filtering (such as metrics) or automatic processing of events, alerts, or incidents based on field values (such as workflow and correlation) include a scope query filter. This filter identifies the items, according to field values, which will be processed.
To use the filter, click inside the filter box.
 |
A list of suggested fields displays. You can select a field from the list, or you can type directly into the filter box.
Supported filter operators include:
equals (=)
not equals (!=)
less than (<)
less than or equal to (<=)
greater than (>)
greater than or equal to (>=)
in
MATCHES
not
AND
OR
The available operators vary depending on context. For example, a field using a string data type like description does not include greater than or less than operators, which are only applicable for numeric values.
Double quotes (or single quotes, as either is acceptable) are only required when a value contains a space. In the UI, you do not have to include double quotes around field names (this is done for you programmatically). In the following examples, double quotes are added to all field names with spaces for clarity.
The following examples show the basic construction of filter queries using simple operators.
severity = Critical
status != closed
"total alerts" >= 10
The right side of the filter operator must always be a value. It cannot be another field. This is an invalid filter:
"last status change time" = "last event time" Warning
Case-sensitivity should not be used as filtering criteria in scope filters. This information is provided to clarify where case-sensitivity currently exists and to help avoid issues caused by case-sensitivity in scope filters. While case-sensitivity support currently exists and could potentially be used in scope filters, case-sensitivity will be removed in a future release, and any filters based on case will become case-insensitive, which could result in different results being matched.
Note
The deduplication process automatically changes the case of fields used in the deduplication key to lowercase, unless a dedupe_key value is specified in the event. For more information on the deduplication key, see Configure incident similarity.
Most field values are currently case-sensitive. The following alert and incident fields are case-insensitive. Incident Management makes no differentiation between lowercase, uppercase, or mixed case for these field values:
Case-insensitive fields in Incident Management |
|---|
All other fields are case-sensitive. |
Therefore, these two key/value pairs are equivalent when evaluated by a scope filter:
"priority" = "p1" | "priority" = "P1" |
But these two are not:
"description" = "metric" | "description" = "METRIC" |
Spaces only matter between parameters and inside double quotes. For example, this query:
severity = Critical OR severity = Major
... is not the same as this query:
severity=CriticalORseverity=Major
... but it is the same as this query:
severity = Critical OR severity = Major
Likewise, this query:
"correlation definition name" = "Similar Sources"
... is not the same as this query:
"correlationdefintitioname" = "SimilarSources"
... or this query:
"correlationdefinition name" = "Similar Sources"
... but it is the same as this one:
"correlation definition name" = "Similar Sources"
To find items where a field has not yet been assigned a value (such as assignee, user groups, maintenance windows, or other field that is not present in the payload until assigned), you can use NULL as the value.
assignee = NULL
NULL indicates the the key is not present, or the key value is NULL. NULL is not the same as blank or an an empty string.
Using a list field like services with the in operator means that the filter looks for the specified strings in the field.
This example:
services in (retail, "pharmaceutical supplies")
...returns true if the services field includes retail, pharmaceutical supplies, or both.
The in operator only returns true when the string specified is included in the list as a field value. The in operator does not match partial values.
For this example:
services in (data)
...the query returns false for the services field for all of these values:
database
"data center"
userdata
rotateddatalog
All list type fields (such as services, classes, tags) support the in operator.
For single value fields, the in operator returns true when the values are equivalent.
This filter:
check in (cpu)
returns true when the check field has the value cpu.
MATCHES compares two values or strings.
In this example, only items where the description field value matches the regex in this string match this scope filter.
description MATCHES "Originates from the 192.168.[0-9]{3}.0 network"A description value of "Originates from the 192.168.089.0 network" is a match.
You can also use the MATCHES operator to perform a contains operation. It can check if the filter string is included in the received data.
This filter:
source MATCHES ".*network.*"
matches source = "AWS network" and source = "North America network router"
You can also use MATCHES with a regex to identify the start and end of strings.
description MATCHES "^1 Source:.*" //matches strings starting with 1 Source:
tags.manager MATCHES ".*Collector$" //matches strings ending with Collector
The MATCHES operator in scope filter queries is case-sensitive by default.
In the example below, a matching payload can contain a severity field with a value of either Critical or Major.
severity = Critical OR severity = Major
In the next example, matching alerts must match all three portions of this query: the assignee is not user1@example.com, a maintenance window was active, and the status is not set to In Progress.
assignee != user1@example.com AND "in maintenance" = true AND status != "In Progress"
severity not in (Unknown, Clear, Minor)
description not MATCHES "PagerDuty alert"
The not operator can be used with other operators to build queries where you want to eliminate certain matching strings. Use != instead of not to indicate that the value should not match a single value (example: manager != collector) because the not operator is not interchangeable with != in the scope query filter.