Filters

You can filter the objects such as entities, metrics, and events by comparing their scalar fields or facts with constants.

All supported object have fields that represent atomic information. You can filter the objects using these fields if the information is of scalar type (not array or object). For example id, raw, and value.

You can also use facts to filter. The facts are the fields that are indirectly associated with the filtered object. For example, attribute or tag of a name.

You may include filter expressions after any function that returns a set of objects.

To include a filter, use a square bracket []. For example:

<identify set of objects>[<expression>]

Supported operations

The following operations are supported in a filter expression:

For example, if you want to fetch a service with the name Test, use the following filter expression:

FETCH id
FROM entities(apm:service)[attributes("service.name") = 'Test']

Set Operations

For comparison of sets, use the standard operators together with a set of constants:

The following table lists the operators along with the description.

Filter with Wildcards

You can use wildcards to filter:

• events by raw field value

• topology entities by attributes or tags

• spans string type fields and attributes or tags

• traces string type fields

• metrics by their attributes, tags or sources

Filter Events with Wildcards

You can filter the texts in the raw fields of events. See Events() Function.

Filter Metrics, Spans, and Traces with Wildcards

You can use wildcards to filter metrics, spans and traces. The wildcard filtering supports the single operator ~.

The only additional special character is asterisk * as a wildcard character. There are no restrictions on the position of the asterisk in the wildcard pattern. To match literal *, it must be escaped with backslash \*.

Example: Get metrics with severity containing letter O from the logs in the c:\Windows\ folder, spans with regex pattern containing the match all .* and traces with source starting with Macy’s.

FROM entities()
FETCH 
    metrics(logs:log_records)[
        attributes("severity") ~ '*O*' 
        && attributes("path") ~ 'c:\\Windows\\*.log'
    ],
    spans[attributes("regex.pattern") ~ '*.\**'],
    traces[source ~ 'Macy\'s*']

Filter Entity with Wildcards

You can filter entities with wildcard patterns. You can form a wildcard pattern with an asterisk (*) wildcard at the beginning and/or at the end of the search text. However, you can not use asterisks in the middle of the search text. For example, ~ '*myvalue*' is correct, but ~ '*my*value*' is incorrect.

UQL supports four types of filters for wildcard patterns:

• starts with - matches any string that begins with the specified text. For this, you need to add an asterisk after the text. For example, ~ 'myvalue*'.

• ends with - matches any string that ends with the specified text. For this, you need to add an asterisk before the text. For example, ~ '*myvalue'.

• contains - matches any string that contains the specified text. For this, you need to add an asterisk before and after the text. For example, ~ '*myvalue*'.

• equals - matches any string that is exactly the specified text. For this, you don't need to add an asterisk to the text. For example, ~ 'myvalue' is same as = 'myvalue'.

You can provide a wildcard pattern that contains asterisks as regular characters, however, you must escape them. For example, for ~ 'my\*value*', all values starting with my*value including the asterisk within the string pass the filter.

Other characters such as ? are considered regular characters without any special meaning.

You can use the following operators to filter an entity with wildcard patterns:

• Like operator (~)
• Not like operator (!~)

For example, you want to filter services by the name that begins with "Foo" and the cloud region that does not contain "no-cloud":

FETCH id
FROM entities(apm:service)[attributes("service.name") ~ 'Foo*' 
                        && tags("cloud.region") !~ '*no-cloud*']

Note You can use the like (~) and the not like (!~) operators in the following cases:

• attributes and tags of entities
• raw fields in events

Use Wildcard Filter in the IN Operator

The value of the IN operator can contain wildcard patterns. Currently, UQL supports only one wildcard pattern as the IN operator value- the asterisk (*) without quoting. For example, attributes("foo") IN [*]. The purpose is to pass the filter condition in all cases. The condition is always evaluated as true.

Example:

FETCH id
FROM entities(k8s:pod)[ attributes("k8s.namespace.name") IN [*] ]

Filter Entity by Observations

You can filter the entities by using observation fields, specifically metric observations. You can use a scalar time-aggregated consumption function of a metric with a specified source.

For example, to fetch the count of services that have errors and calls per minute less than 10:

FETCH 
    count,
    metrics(calls_min, apm).value
FROM entities(apm:service)[
    metrics(errors, 'sys:derived').sum > 0 
    && metrics(calls_min, apm).value < 10
]

When entities are filtered by a metric observation, the condition is evaluated per each entity. But when a metric observation is specified in the FETCH clause, the resulting metric is for the whole aggregation group.

In the preceding example, the fetched metric call_min is aggregated across all the entities of the single returned aggregation group that consists of count entities.

Filter Observations by Topology Dimension

You can use a topology dimension as an additional filter for observations. For this, you must first specify an alias for the topology dimension and then use it in the filter expression. For example:

FETCH 
    place: attributes(location),
    metrics(calls_min)[attributes(location) = place]
FROM entities(service_type)

Note

The place is treated as a reference to the aliased attributes(location) and not as just a string.

Filter by hasTag

The function hasTag(<tag-name>) resolves to true if the associated entity has a tag <tag-name> with a value or a null value. This function supports the multi-tag concept.