This guide describes the use of monitoring filters to specify monitored resources, metric types, group definitions, and time series.
For an introduction to metrics, time series, and monitored resources, see Metrics, Time Series, and Resources.
Filters make extensive use of labels; see Labels for additional information.
Using filters
You can use filters in the Monitoring API v3 to do the following:
Retrieve time series. Use a filter to select time series data based on the data's project, group, monitored resource properies, and metric properties. For more information and examples, see Retrieving time series data.
Define the resources in a group. Use a filter to assign resources to a
Group
based on the resources' properties and the project to which they belong. For more information and examples, see Defining group membership.List group members. Use a filter to select resources within a group based on the resources' properties and the project to which they belong. For more information and examples, see Listing group members.
List metric descriptors. Use a filter to inspect particular metric types from the hundreds of defined types in Monitoring. For more information and examples, see Listing metric descriptors.
List monitored resource descriptors. Use a filter to inspect particular monitored resource types from the dozens of defined types in Monitoring. For more information and examples, see Listing monitored resource descriptors.
Depending on which of the preceding operations you are constraining, your filter
can consist of the logical AND
of the selectors in the following
list. These are simple examples—there are several kinds of comparison
operators, for instance.
Project selector: Restricts the filter match to objects that belong to one or more projects within the Workspace mentioned in the method's
name
parameter.project = "project-id-or-number" OR project = "another-id-or-number"
Group selector: Matches resources belonging to a (single)
Group
. For example:group.id = "group-id"
Resource selector: Matches monitored resources of a particular type or having particular label values. For example, here are different ways to specify resource information:
resource.type = "the_resource_type" resource.labels.a_label_for_the_resource_type = "label_value"
Metric selector: Restrict the filter to metrics or time series of a particular metric type or having particular label values. For example, here are different ways to specify metric types:
metric.type = "the_metric_type" metric.labels.a_label_for_the_metric_type = "label_value"
The following table shows which selectors are permitted in filters based on what the filter is used to do:
Filter purpose | Project selector | Group selector | Resource selector | Metric selector |
---|---|---|---|---|
Define groups | yes | yes1 | ||
List group members | yes | yes | ||
List time series | yes | yes | yes | yes2 |
List metric descriptors | yes | yes | ||
List monitored resource descriptors | yes |
2 When listing time series, you must specify exactly one metric type.
The following sections show examples of typical uses of monitoring filters. See Filter syntax for a complete discussion of the available filter objects and operators.
Retrieving time series data
Method:
projects.timeSeries.list
Filter objects: project
, group.id
, resource.type
,
resource.labels.[KEY]
, metric.type
, metric.labels.[KEY]
A time series is a list of time-stamped data points of a metric type from a specific monitored resource. For details, see The metric model. The metric type is specified by a metric descriptor, and the monitored resource is specified by a monitored-resource descriptor. Filters must include a metric selector and that selector must specify exactly one metric type.
All time series for a particular metric type:
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Time series that relate to resources in a specific group. The
group
selector only works with aligned time series data; see Group selector for more information:group.id = "2468013579" AND metric.type = "compute.googleapis.com/instance/cpu/usage_time"
Time series from a specific Compute Engine instance:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = "my-instance-name"
Time series from similarly-named Compute Engine instances:
metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = starts_with("frontend-")
Time series from Compute Engine instances that start with
gke-hipster
orgke-nginx
:metric.type = "compute.googleapis.com/instance/cpu/usage_time" AND metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
Defining group membership
Method:
projects.groups
Filter objects: project
, resource.type
, resource.labels.key
,
metadata.system_labels.[KEY]
, metadata.user_labels.[KEY]
A group can contain any number of resources, as specified by a filter. Group
membership is dynamic; more or fewer resources might match the filter every time
the filter is evaluated. The name
parameter in the Group
object specifies the group and the owning Workspace. If the project
object is used in the filter, it must specify a project that is a member of
the Workspace.
All Compute Engine VM instances in Europe:
resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")
Listing group members
Method:
projects.groups.members.list
Filter objects: project
, resource.type
, resource.labels.[KEY]
Use a filter to limit which group members you retrieve. The name
parameter to
the method specifies a Workspace and a group defined in the
Workspace. If the project
object is used in the filter, it must specify a
project that is a member of the Workspace.
All the Cloud Pub/Sub topic resources that belong to project
my-project
:project = "{my-project}" AND resource.type = "pubsub_topic"
Listing metric descriptors
Method:
projects.metricDescriptors.list
Filter objects: project
, metric.type
Use a filter to limit which metric descriptors you retrieve:
All the Compute Engine metrics:
metric.type = starts_with("compute.googleapis.com")
See Metric List for a complete list of the metric types defined by Monitoring. For an overview of how metrics are named, see Naming conventions and requirements.
Listing monitored resource descriptors
Method:
projects.monitoredResourceDescriptors.list
Filter objects: resource.type
Use a filter to limit which monitored resource descriptors you retrieve:
All the Cloud Pub/Sub monitored resource descriptors.
resource.type = starts_with("pubsub")
See Monitored Resource List for a complete list of the monitored resource types defined by Monitoring.
Reference: filter syntax
For an overview of filters with examples, see Using filters.
A monitoring filter is a string consisting of up to four types of selectors:
<monitoring_filter> ::= <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>
The filter matches an item if all of the included selectors match the item. As
described in the following sections, some selectors can have multiple
comparisons joined by AND
or OR
.
Depending on the filter's purpose, certain selectors might be required, optional, or prohibited. For example, the filter that defines the resources in a group cannot contain a metric selector, because groups do not contain metric types or time series. On the other hand, the filter used to list time series must contain a metric selector. The order of the selectors in the filter does not matter, but comparisons for different selectors must not be intermingled.
Comparisons
Filters and their selectors are built from comparisons. Each comparison has the following form:
[OBJECT] [OPERATOR] [VALUE]
These elements are described below:
[OBJECT]: selects a value to be tested, one of the following:
project group.id metric.type metric.labels.[KEY] resource.type resource.labels.[KEY] metadata.system_labels.[KEY] metadata.user_labels.[KEYSTRING]
[KEY] is a name, such as
zone
orinstance_id
. [KEYSTRING] can be name, but if it contains special characters then it must be quoted with quotation marks ("
).[OPERATOR]: a comparison operator, one of the following:
= # equality (case-sensitive) > < >= <= # numeric ordering != # not equal : # "has" substring match and test for key (case-sensitive)
[VALUE]: a literal value or a built-in function call, one of the following
<string> # "a Unicode string". Don't use apostrophes (`'`) to quote strings. <bool> # true or false <number> # 0, -2, 123456, 3.14156 <function> # operators on the right side of '=' or '!=': # starts_with(<string>) # ends_with(<string>) # has_substring(<string> [, ignore_case=false]) # one_of(<string>,...,<string>) for up to 100 strings # monitoring.regex.full_match(<RE2-string>)
Except in the case of
timeSeries.list
, thehas_substring
filter takes an optional second argument, which specifies whether the match ignores case or not. The default value isfalse
, so the default match is case-sensitive:- Case-sensitive:
display_name=has_substring("Demo")
- Case-sensitive:
display_name=has_substring("Demo", false)
- Case-insensitive:
display_name=has_substring("Demo", true)
Only the
has_substring(<string>)
form is supported fortimeSeries.list
.The
monitoring.regex.full_match
filter takes a regular-expression string in RE2 syntax.- Case-sensitive:
You can use the following operators to group or modify comparisons. OR
has
higher precedence than AND
. The operators must be written in upper case:
(...) # grouping comparisons
AND # conjunction (optional but recommended)
OR # disjunction
The AND
operator can be omitted between operators, but it is clearer and
less error-prone to include it.
The comparison x = one_of("a", "b", "c")
is equivalent to
(x = "a" OR x = "b" OR x = "c")
Only in group definitions, you can use the unary negation operator before a comparison, but not before a parenthesized expression:
NOT # negates the following comparison
Filter selectors
Use selectors to limit the filter selections to certain items.
In the following sections, braces are used to show repetition. For example, the
notation <x> {OR <y>}
means you can write any of the following:
<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...
Project selector
A project selector limits the filter selection to items belonging to a single project or to any one of a set of projects. Each project can be specified by its ID or its number:
<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}
If your project selector has more than a single comparison, enclose the entire selector in parentheses for better readability. For example:
(project=12345 OR project="my-project-id") AND resource.type="gce_instance"
Group selector
A group selector limits the filter selection to items belonging to a single group:
<group_selector> ::= group.id '=' <string>
For example, the following filter could be used to retrieve a time series from each of the VM instances in a group:
group.id = 12345 AND
resource.type = "gce_instance" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
The group selector is only permitted in filters passed to
projects.timeSeries.list
. In addition, group selection
requires aligned data; that is, the call to
projects.timeSeries.list
must include values for
perSeriesAligner
and alignmentPeriod
. This is because group membership is
itself a kind of time series that must be joined with the metric data, and
supplying alignment parameters gives you control over how that join happens.
For more information on alignment parameters, see
Aggregating data.
Resource selector
A resource selector limits the filter selection to resources—or items associated with resources—that have a specific resource type or label values:
<resource_selector> ::= <resource_type_expression>
| <resource_label_expression>
| <resource_type_expression> AND <resource_label_expression>
<resource_type_expression> ::= resource.type '=' <string>
| resource.type ':' <string>
| resource.type '=' starts_with '(' <string>')'
| resource.type '=' ends_with '(' <string> ')'
<resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}
| <r_label_comparison> {OR <r_label_comparison>}
<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)
| resource.labels.[KEY] ':' <string>
| resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'
| resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>
If you use more than one <r_label_comparison>
in your selector, enclose them
all in parentheses for better readability. For example, the following filter
could be used to define a group that includes all VM instances in the USA and
Europe:
resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
Resource selector for group definitions
Resource selectors used to define group membership use extensions to the
<resource_selector>
syntax:
You can use the names
metadata.system_labels.[KEY]
andmetadata.user_labels.[KEYSTRING]
in comparisons in the same way asresource.labels.[KEY]
. The keys formetadata.user_labels
should be quoted because they can contain special characters such as hyphens.You can use the not-equals operator (
!=
) to compare resource types, resource labels, and metadata. The operator can be used when comparing strings, numbers, Booleans, or the substring functions. For example,resource.type!=starts_with("gce")
is true if the resource type does not start with"gce"
.You can use a single
NOT
operator before any resource comparison. For example,NOT resource.labels.zone:"europe"
is true if the resource's zone does not include"europe"
. You cannot useNOT
before a parenthesized expression.You can use the exists operator (
:
) to test for the existence of keys. For example, the comparisonresource.labels.zone
is true if the label keyzone
is present in the resource.
For example, one of the platform resource metadata keys for VM instances is
spot_instance
. The following filter selector chooses instances that are
spot instances:
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
Metric selector
A metric selector specifies certain metrics or metric descriptors by limiting the metric type and metric labels. When listing time series data, the metric selector must specify a single metric type:
<metric_selector> ::= <metric_name_expression> [AND <metric_label_expression>]
<metric_name_expression> ::= metric.type '=' <string>
| metric.type ':' <string>
| metric.type '=' starts_with '(' <string> ')'
| metric.type '=' ends_with '(' <string> ')'
<metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}
| <metric_label_comparison> {OR <metric_label_comparison>}
<metric_label_comparison> ::= metric.labels.[KEY] '=' <string> | <bool>
| metric.labels.[KEY] ':' <string>
| metric.labels.[KEY] '=' starts_with '(' <string> ')'
| metric.labels.[KEY] '=' ends_with '(' <string> ')'
| metric.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number>
For example, the following filter could be used to retrieve a time series for a specific database instance:
metric.type = "cloudsql.googleapis.com/database/state" AND
(metric.labels.resource_type = "instance" AND
metric.labels.resource_id = "abc-123456")
Examples
In the filtering examples, we use the following metric descriptor, monitored resource descriptor, and virtual machine instance, simplified for illustration:
# Metric descriptor:
{ "name": "projects/my-project-id/metricDescriptors/compute.googleapis.com%2Finstance%2Fdisk%2Fread_bytes_count"
"type": "compute.googleapis.com/instance/disk/read_bytes_count",
"labels": [ { "key": "device_name",
"description": "The name of the disk device." } ] }
# Monitored resource descriptor:
{ "name": "monitoredResourceDescriptors/gce_instance"
"type": "gce_instance",
"labels": [
{ "key": "instance_id",
"description": "The instance ID provide by Google Compute Engine." },
{ "key": "zone",
"description": "The Google Cloud Platform zone hosting the instance."
} ] }
# Resource descriptor for a virtual machine instance.
{ "type": "gce_instance",
"instance_id": "1472038649266883453",
"zone": "us-east-1b",
"disks": [ "log_partition" ],
"machine_type": "n1-standard-2",
"tags": { "environment": "bleeding-edge",
"role": "frobulator" },
"project_id": "my-project-id" }
Metric retrieval examples
To request the disk read bandwidth usage for all instances and all devices, define a filter as shown below. This returns, for each instance, a separate time series reporting the read bandwidth for each device:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"
To refine the request to query for the read bandwidth for only the disk device known as "log_partition" on each instance, define the filter as shown below. This filter returns, for each instance, at most one time series, depending on whether a device of that name exists on that instance:
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"
To restrict the request to just a single instance, specify that instance:
resource.type = "gce_instance" AND
resource.labels.instance_id = "1472038649266883453" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" AND
metric.labels.device_name = "log_partition"
Filtering with groups
The following examples illustrate the use of the group selector in filters to restrict monitored resources to those in a specific group. See Group definitions for information on the selectors used to define group membership.
{ "name": "projects/my-test-project/groups/024681012",
"display_name": "My Redis Cluster",
"filter": "metadata.user_labels.role=redis" }
In a call to the projects.timeSeries.list
method, the
following filter requests the disk read bandwidth usage for all Compute Engine
instances in a particular group. The group must be
defined in the Workspace specified in the method's name
parameter:
resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"