Reference to the filter() function

Summary

filter(<tsExpression>, <filter1> [and|or [not] <filter2>] ... )

where <filterN> is:
    <metricName> | source="<sourceName>" | <pointTagKey>="<pointTagValue>"

Filters the expression to display only the time series that match one or more filters, which might be any combination of metric names, source names, or point tags.

Parameters

ParameterDescription
tsExpression Expression that describes the time series you want to filter.
<metricName>|source=|tag=|<pointTagKey>= A metric, source, source tag, or point tag to filter by. You must specify at least one filter, which can be of any type. Use Boolean operators to combine multiple filters. For example,
(source=app-1 or source=app-2) and env=dev.

Description

The filter() function filters the expression to display only the time series that match the specified metric, source, point tag, or combination of these filters.

filter() is similar to retainSeries(), but does not support matching a source tag.

The advantage of using filter() is that it’s very clear that the filtering is going on; that helps other users understand your query.

Point Tag Filters

Use point tags to add extra dimensions to individual data values. While source tags are great for filtering your data to just the sources that are important to your use case, they do not store historical data. If your company uses a cloud-computing platform, then you might see instances constantly being re-provisioned as they are spun up and shut down. In those cases, historical data can be very important.

Point tags are tied to individual data values, and allow you to create queries based on historical data. Point tags are expressed as <pointTagKey> = <pointTagValue>. The pointTagKey and pointTagValue are unique to each customer. For example, let’s say that source app-1 is reporting data values for application BLUE to metric cpu.loadavg.1m. However the next day app-1 is re-provisioned and is now reporting data values for application RED. The data values reported by app-1 can include a pointTagKey of app and a pointTagValue of red and blue. You could then construct the following query to only see data values for application blue:

ts(“cpu.loadavg.1m”, source=“app-1” and app=“blue”)

Examples

The following example filters the disk space used metrics to show only the data for certain sources. We use a wildcard character to get both app-2 and app-20 app-2*.

The advantage of using filter() is that it’s very clear that the filtering is going on; that helps other users understand your query.

filter example