This guide describes how to configure filters when you use theMonitoring API.You use filters to specify monitored resources, metric types, group definitions,and time series. You can also use a filter to configure an alerting policy thatmonitorsprocesses running on your systems. For information about those filters,seeProcess-health filters.

Before you begin

If you aren't familiar with metrics, time series, and monitored resources,seeMetrics, time series, and resources.

If you aren't familiar with labels, seeLabels for anintroduction.

Using filters

You can use filters in theMonitoring APIto do the following:

• Select the specifictime series data that isreturned from alist API request.The filter can select time seriesbased on the data's project, group, monitored resource properties, andmetric properties. For more information and examples, seeRetrieving time series data.

• Assign resources to aGroup based on the resources' properties and theproject to which they belong. For more information and examples,seeDefining group membership.

• Select resources within a groupbased on the resources' properties.For more information and examples, seeListing group members.

• List particular metric types. For moreinformation and examples, seeListing metric descriptors.

• List particular monitored resource types. For more information andexamples, seeListing monitored resource descriptors.

Filter selectors

A filter consists of at least oneselector, which is a filter keyword.The following examples illustrate the different selectors:

• project: Matches when the metrics of the specified project are visible to the scoping project of a metrics scope mentioned in thename parameter.

  Use theproject selector when a Google Cloud project can view the metrics of multiple Google Cloud projects or AWS accounts and you only want metrics for single project. For example, if themetrics scope forProject-A includesProject-B, then a match occurs whenname has a value ofProject-A and you use the following filter:

  project = "Project-B"

• group: Matches resources belonging to oneGroup.

  The following filter matches the group with the identifiergroup-id:

  group.id = "group-id"

• resource: Matches monitored resources of a particular type or having particular label values.

  • The following filter matches all monitored resources that are Compute Engine virtual machine (VM) instances:

    resource.type = "gce_instance"

  • The following filter matches all resources whose zone begins witheurope-:

    resource.labels.zone = starts_with("europe-")

• metric: Matches a particular metric type ortime series with with a particular label that matches a specific value.

  • The following filter matches a specific metric type:

    metric.type = "compute.googleapis.com/instance/cpu/usage_time"

  • The following filter matches time series with a label namedinstance_name, whose value starts withgke-hipster orgke-nginx:

    metric.labels.instance_name = monitoring.regex.full_match("gke-(hipster|nginx).*")

The following table shows which selectors are permitted in filters based ontheMonitoring API call:

The following sections show examples of typical uses of monitoring filters.SeeFilter syntax for a completediscussion 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 aspecific monitored resource. For details, seeThe metric model.The metric type is specified by ametric descriptor, andthe monitored resource is specified by amonitored-resource descriptor.

The filter specified to thetimeSeries.list method must include ametric selector, and that selector must specify exactly one metric type:

• To return all time series for a particular metric type:

  metric.type = "compute.googleapis.com/instance/cpu/usage_time"

• To return all time series for a specific group. Thegroup selector only works with aligned time series data; seeGroup selector for more information:

  metric.type = "compute.googleapis.com/instance/cpu/usage_time" ANDgroup.id = "2468013579"

• To return all time series from a specific Compute Engine instance,use the following filter:

  metric.type = "compute.googleapis.com/instance/cpu/usage_time" ANDmetric.labels.instance_name = "my-instance-name"

• Return all time series from Compute Engine instances whose namesstart withfrontend-, use the following filter:

  metric.type = "compute.googleapis.com/instance/cpu/usage_time" ANDmetric.labels.instance_name = starts_with("frontend-")

• Return all time series from Compute Engine instances whose namesstart withgke-hipster orgke-nginx, use the following filter:

  metric.type = "compute.googleapis.com/instance/cpu/usage_time" ANDmetric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")

Defining group membership

Method:projects.groups.create
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. Groupmembership is dynamic; more or fewer resources might match the filter everytime the filter is evaluated. Thename parameter in theGroup object specifies the group and thescoping project of a metrics scope.If theproject selector is used in the filter, then it must specify aproject whose metrics are visible to the scoping project.

For example, to create a group that includes only Compute Enginevirtual machine (VM) instances in Europe, use the following filter:

resource.type = "gce_instance" AND resource.labels.zone = starts_with("europe-")

For information about API methods that you can use to delete, update, or listgroups, seeprojects.groups API reference page.

Listing group members

Method:projects.groups.members.list
Filter objects:project,resource.type,resource.labels.[KEY]

Thename parameter specifies ascoping project of a metrics scope and a group defined inthat project. If you don't specify a filter, thenprojects.groups.members.listreturns a list of the membership of the group.

You can use a filter to limit which group members you retrieve. If the filterincludes aproject selector, then the selectors value must specify a projectwhose metrics are visible to the scoping project. If an invalid value isspecified, then theproject selector is ignored.

For example, suppose that you create a group that includes all resourceswhose name containstest. To list only the group membersthat are Pub/Sub topics, use the following filter:

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.

For example, to return only the Compute Engine metric descriptors,use the following filter:

metric.type = starts_with("compute.googleapis.com")

SeeMetrics list for a complete list of the available metrictypes. For an overview of how metrics are named, seeMetric namingconventions.

Listing monitored resource descriptors

Method:projects.monitoredResourceDescriptors.list
Filter objects:resource.type

Use a filter to limit which monitored resource descriptors you retrieve.

For example, to retrieve only the Pub/Submonitored resource descriptors, use the following filter:

resource.type = starts_with("pubsub")

SeeMonitored resource list for a complete list ofthe monitored resource types defined by Monitoring.

Examples

In the filtering examples, we use the following metric descriptor,monitored resource descriptor, and virtual machine instance, simplified forillustration:

    # 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.type = "compute.googleapis.com/instance/disk/read_bytes_count"

metric.type = "compute.googleapis.com/instance/disk/read_bytes_count" ANDmetric.labels.device_name = "log_partition"

resource.type = "gce_instance" ANDresource.labels.instance_id = "1472038649266883453" ANDmetric.type = "compute.googleapis.com/instance/disk/read_bytes_count" ANDmetric.labels.device_name = "log_partition"

The following examples illustrate the use of thegroup selector in filters to restrict monitored resourcesto those in a specific group. SeeResource selector for group definitionsfor 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 theprojects.timeSeries.list method,the following filter requests the disk-read bandwidth usage for allCompute Engine instances in a particular group. The group must bedefined in thescoping project of a metrics scope specified in themethod'sname parameter:

resource.type = "gce_instance" ANDgroup.id = "024681012" ANDmetric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

Reference: filter syntax

For an overview of filters with examples, seeUsing 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 multiplecomparisons joined byAND orOR. The order of the selectors in thefilter doesn't matter, but comparisons for different selectors must not beintermingled.

Depending on the filter's purpose, certain selectors might be required,optional, or prohibited. For example, the filter used to list time seriesmust contain a metric selector.However, the filter that defines the resources in a group can'tcontain a metric selector, because groups don't contain metric types ortime series.

Comparisons

Filters and their selectors are built from comparisons. Eachcomparison has the following form:

• [OBJECT]: selects a value to be tested; one of the following:

  projectgroup.idmetric.typemetric.labels.[KEY]resource.typeresource.labels.[KEY]metadata.system_labels.[KEY]metadata.user_labels.[KEYSTRING]

  [KEY] is a name, such aszone 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 when used in thetimeSeries.list method, 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)

  When used in thetimeSeries.list method, only thehas_substring(<string>) form is supported.

  Themonitoring.regex.full_match filter takes a regular-expression string inRE2 syntax.

You can use the following operators to group or modify comparisons.OR hashigher precedence thanAND. The operators must be written in upper case:

(...)        # grouping comparisonsAND          # conjunction (optional but recommended)OR           # disjunction

TheAND operator can be omitted between operators, but it is clearer andless error-prone to include it.

The comparisonx = one_of("a", "b", "c") is equivalent to the following:

(x = "a" OR x = "b" OR x = "c")

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 that you can write any of thefollowing:

<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 singleproject or to any one of a set of projects. Each project can be specified byits 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 entireselector 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 singlegroup:

<group_selector> ::= group.id '=' <string>

For example, the following filter can be used to retrieve a time seriessfrom each of the VM instances in a group:

group.id = 12345 ANDresource.type = "gce_instance" ANDmetric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

The group selector is permitted only in filters passed to theprojects.timeSeries.list method. In addition,group selection requiresaligned data; that is, theprojects.timeSeries.list call must include values for the fieldsperSeriesAligner andalignmentPeriod. This is because group membership isitself a kind of time series that must be joined with the metric data, andsupplying alignment parameters gives you control over how that join happens.For more information on alignment parameters, seeAggregating data.

Resource selector

A resource selector limits the filter selection to resources—or itemsassociated with resources—that have a specific resource type or labelvalues:

<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> ')'<r_label_comparison> ::= resource.labels.[KEY] '=' (<string> | <bool>)                       | resource.labels.[KEY] ':' <string>                       | resource.labels.[KEY] '=' (starts_with | ends_with) '(' <string> ')'                       | resource.labels.[KEY] ('=' | '>' | '<' | '>=' | '<=') <number><resource_label_expression> ::= <r_label_comparison> {AND <r_label_comparison>}                              | <r_label_comparison> {OR <r_label_comparison>}

If you use more than one<r_label_comparison> in your selector, thenenclose them all in parentheses for better readability.For example, the following filter could be used to define a group that includesall Compute Engine 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 include filters based on the value of metadata system labels,metadata.system_labels.[KEY], and metadata user labels,metadata.user_labels.[KEYSTRING]. We recommend quoting thekeys formetadata.user_labels because they can contain specialcharacters such as hyphens.

  When a selector contains a metadata filter and a resource filter, youmust combine them withAND; you can't useOR. For example, a chartwith the following selector displays the CPU utilization for all VMinstances with a machine type ofe2-medium ore2-micro:

  metric.type="compute.googleapis.com/instance/cpu/utilization"resource.type="gce_instance" AND(metadata.system_labels."machine_type"="e2-medium" ORmetadata.system_labels."machine_type"="e2-micro")

• You can use the not-equals operator (!=) to compare resource types,resource labels, and metadata. The operator can be used when comparingstrings, numbers, Booleans, or the substring functions. For example,resource.type!=starts_with("gce") is true if the resource type does notstart with"gce".

• You can use a singleNOT operator before a resource comparison. Forexample,NOT resource.labels.zone="europe" is true if theresource's zone doesn't include"europe". You can't useNOT beforean exists operator (:) or 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 labelkeyzone is present in the resource.

For example, one of the platform resource metadata keys for VM instances isspot_instance. The following filter selector chooses instances that arespot instances:

resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true

Metric selector

A metric selector specifies certain metrics or metric descriptors by limitingthe metric type and metric labels. When used with theprojects.timeSeries.list method,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_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><metric_label_expression> ::= <metric_label_comparison> {[AND] <metric_label_comparison>}                            | <metric_label_comparison> {OR <metric_label_comparison>}

For example, the following filter could be used to retrieve a timeseries 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")