Reference to the filter() function

Summary

filter(<expression> [, <metric>|source=|tagk=<pointTagKey>])

Filters the expression to display only the time series that match the specified metric, source, or point tag. To filter by a particular source or point tag, specify source= or tagk=, respectively. You can specify only one filtering parameter per function call.

Parameters

ParameterDescription
expression Expression that you want to filter.
metric|source=|tagk= The metric, source or point tag to filter by.

Description

The filter() function filters the expression to display only the time series that match the specified metric, source, or point tag. To filter by a particular source or point tag, specify source= or tagk=, respectively. Set pointTagKey to the unique point tag key to filter by.

You can specify only one filtering parameter (metric, source, or point tag) per function call. To filter by multiple parameters, use a filter() call for each parameter. filter() is similar to retainSeries(), but does not support matching a source tag.

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 app-10. 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