监控过滤器

本指南介绍如何使用监控过滤条件指定受监控的资源、指标类型、组定义和时间序列。

如需了解指标、时间序列和受监控的资源，请参阅指标、时间序列和资源。

过滤条件广泛使用标签；请参阅标签了解详情。

使用过滤器

您可以使用 Monitoring API v3 中的过滤条件执行以下操作：

检索时间序列。根据数据的项目、组、受监控的资源属性和指标属性，使用过滤条件选择时间序列数据。如需了解详情和示例，请参阅检索时间序列数据。
定义组中的资源。根据资源的属性及其所属的项目，使用过滤条件将资源分配给 Group。如需了解详情和示例，请参阅定义组成员资格。
列出组成员。根据资源的属性及其所属的项目，使用过滤条件选择组中的资源。如需了解详情和示例，请参阅列出组成员。
列出指标描述符。使用过滤条件从 Monitoring 中的数百个已定义类型中查看特定指标类型。如需了解详情和示例，请参阅列出指标描述符。
列出受监控的资源描述符。使用过滤条件从 Monitoring 中的数十个已定义类型中查看特定受监控的资源类型。如需了解详情和示例，请参阅列出受监控的资源描述符。

根据您要限制的上述操作，您的过滤条件可以包含以下列表中选择器的逻辑 AND。这些是简单的示例，例如，有多种比较运算符。

项目选择器：将过滤条件限制为属于方法的 name 参数中提到的工作区中的一个或多个项目的对象。
```
project = "project-id-or-number" OR project = "another-id-or-number"
```
组选择器：匹配属于单个 Group 的资源。例如：
```
group.id = "group-id"
```
资源选择器：匹配特定类型或具有特定标签值的受监控的资源。例如，以下是指定资源信息的不同方式：
```
resource.type = "the_resource_type"
resource.labels.a_label_for_the_resource_type = "label_value"
```
指标选择器：将过滤条件限制为特定指标类型或具有特定标签值的指标或时间序列。例如，以下是指定指标类型的不同方法：
```
metric.type = "the_metric_type"
metric.labels.a_label_for_the_metric_type = "label_value"
```

下表显示了不同用途的过滤条件可以使用的选择器：

过滤条件用途	项目选择器	组选择器	资源选择器	指标选择器
定义组	是		是¹
列出群组成员	是		是
列出时间序列	是	是	是	是²
列出指标描述符	是			是
列出受监控的资源描述符			是

¹ 资源选择器在定义组成员资格时有其他选项。
²列出时间序列时，必须仅指定一种指标类型。

以下部分显示了监控过滤条件的典型用法示例。有关可用过滤条件对象和运算符的完整讨论，请参阅过滤条件语法。

检索时间序列数据

方法：projects.timeSeries.list
过滤对象：project、group.id、resource.type、resource.labels.[KEY]、metric.type、metric.labels.[KEY]

时间序列是来自特定受监控的资源的指标类型时间戳数据点的列表。如需了解详情，请参阅指标模型。指标类型由指标描述符指定，受监控的资源由受监控的资源描述符指定。过滤条件必须包含指标选择器，并且该选择器必须仅指定一种指标类型。

特定指标类型的所有时间序列：

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

与特定组中的资源相关的时间序列。group 选择器仅适用于校准的时间序列数据；如需了解详情，请参阅组选择器：
```
group.id = "2468013579" AND
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```

某个特定 Compute Engine 实例的时间序列：

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

类似名称的多个 Compute Engine 实例的时间序列：

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

以 gke-hipster 或 gke-nginx 开头的 Compute Engine 实例中的时间序列：

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

定义组成员资格

方法：projects.groups
过滤对象：project、resource.type、resource.labels.key、metadata.system_labels.[KEY]、metadata.user_labels.[KEY]

一个组可以包含任意数量的资源（由过滤条件指定）。群成员资格是动态的；每次计算过滤条件时，可能有更多或更少的资源与该过滤条件匹配。Group 对象中的 name 参数指定组和所属的工作区。如果在过滤条件中使用 project 对象，则必须指定一个属于该工作区的项目。

欧洲的所有 Compute Engine 虚拟机实例：

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

列出组成员

方法：projects.groups.members.list
过滤对象：project、resource.type、resource.labels.[KEY]

使用过滤条件限制要检索的组成员。方法的 name 参数指定工作区和在工作区中定义的组。如果在过滤条件中使用 project 对象，则必须指定一个属于该工作区的项目。

属于项目 my-project 的所有 Cloud Pub/Sub 主题资源：

project = "{my-project}" AND resource.type = "pubsub_topic"

列出指标描述符

方法：projects.metricDescriptors.list
过滤对象：project、metric.type

使用过滤条件限制要检索的指标描述符：

所有 Compute Engine 指标：

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

如需查看由 Monitoring 定义的指标类型的完整列表，请参阅指标列表。如需简要了解指标的命名方式，请参阅命名规则和要求。

列出受监控的资源描述符

方法：projects.monitoredResourceDescriptors.list
过滤对象：resource.type

使用过滤条件限制要检索的受监控的资源描述符：

所有 Cloud Pub/Sub 受监控的资源描述符。
```
resource.type = starts_with("pubsub")
```

如需查看由 Monitoring 定义的受监控的资源类型的完整列表，请参阅受监控的资源列表。

参考：过滤条件语法

有关过滤条件的概览和示例，请参阅使用过滤条件。

监控过滤条件是一个字符串，最多包含四种类型的选择器：

<monitoring_filter> ::=  <project_selector> AND <group_selector> AND <resource_selector> AND <metric_selector>

如果过滤条件包含的所有选择器都匹配某一项，则过滤条件匹配该项。如以下部分所述，一些选择器可以通过 AND 或 OR 联接多项比较。

根据过滤条件的用途，某些选择器可能是必需的、可选的或禁止的。例如，用于定义组中资源的过滤条件不能包含指标选择器，因为组不包含指标类型或时间序列。另一方面，用于列出时间序列的过滤条件必须包含指标选择器。选择器在过滤条件中的顺序无关紧要，但不同选择器的比较不得相互干扰。

比较

过滤条件及其选择器是通过比较构建的。每个比较都具有以下形式：

[OBJECT] [OPERATOR] [VALUE]

这些元素具体说明如下：

[OBJECT]：选择要测试的值，可以是以下之一：
```
project
group.id
metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]
metadata.system_labels.[KEY]
metadata.user_labels.[KEYSTRING]
```
[KEY] 是一个名称，例如 zone 或 instance_id。[KEYSTRING] 可以是名称，但如果其中包含特殊字符，则必须用引号 (") 引起。

[OPERATOR]：比较运算符，可以是以下之一：

=            # equality (case-sensitive)
> < >= <=    # numeric ordering
!=           # not equal
:            # "has" substring match and test for key (case-sensitive)

[VALUE]：字面量值或内置函数调用，可以是以下之一
```
<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>)
```
除了 timeSeries.list 之外，has_substring 过滤条件接受可选的第二个参数，该参数指定匹配是否忽略大小写。默认值为 false，因此默认匹配区分大小写：
- 区分大小写：display_name=has_substring("Demo")
- 区分大小写：display_name=has_substring("Demo", false)
- 不区分大小写：display_name=has_substring("Demo", true)
timeSeries.list 仅支持 has_substring(<string>) 表单。

monitoring.regex.full_match 过滤条件接受 RE2 语法的正则表达式字符串。

您可以使用以下运算符对比较进行分组或修改。OR 的优先级高于 AND。运算符必须采用大写形式：

(...)        # grouping comparisons
AND          # conjunction (optional but recommended)
OR           # disjunction

可以在运算符之间省略 AND 运算符，但加入它会清晰而且不容易出错。

比较 x = one_of("a", "b", "c") 等同于

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

仅在组定义中，您可以在比较之前使用一元否定运算符，但不能在带括号的表达式之前使用：

NOT          # negates the following comparison

过滤条件选择器

使用选择器将过滤条件选择限制为特定项。在以下部分中，大括号用于显示重复。例如，表示法 <x> {OR <y>} 表示您可以编写以下任何一项：

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

项目选择器

项目选择器将过滤条件选择限制为属于单个项目或一组项目中的任何项目的项。每个项目都可以通过其 ID 或编号来指定：

<project_selector> ::= project '=' (<number> | <string>) {OR project '=' (<number> | <string>)}

如果您的项目选择器有多个比较，请将整个选择器用括号括起，以提高可读性。例如：

(project=12345 OR project="my-project-id") AND resource.type="gce_instance"

组选择器

组选择器将过滤条件选择限制为属于单个组的项：

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

例如，以下过滤条件可用于从组中的每个虚拟机实例检索时间序列：

group.id = 12345 AND
    resource.type = "gce_instance" AND
    metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"

只有在传递给 projects.timeSeries.list 的过滤条件中才允许使用组选择器。此外，组选择还要求校准的数据；也就是说，对 projects.timeSeries.list 的调用必须包含 perSeriesAligner 和 alignmentPeriod 的值。这是因为组成员资格本身是一种必须与指标数据联接的时间序列，而提供校准参数可让您控制联接的发生方式。如需详细了解校准参数，请参阅聚合数据。

资源选择器

资源选择器将过滤条件选择限制为具有特定资源类型或标签值的资源（或与资源关联的项）：

<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>

如果您在选择器中使用多个 <r_label_comparison>，请将它们用括号括起，以提高可读性。例如，以下过滤条件可用于定义一个组，其中包含美国和欧洲的所有虚拟机实例：

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

组定义的资源选择器

用于定义组成员资格的资源选择器使用 <resource_selector> 语法的扩展：

您可以按照与 resource.labels.[KEY] 相同的方式在比较中使用名称 metadata.system_labels.[KEY] 和 metadata.user_labels.[KEYSTRING]。metadata.user_labels 的键应带有英文引号，因为它们可能包含连字符等特殊字符。
您可以使用不等于运算符 (!=) 比较资源类型、资源标签和元数据。在比较字符串、数字、布尔值或子字符串函数时，可以使用该运算符。例如，如果资源类型不是以 "gce" 开头，则 resource.type!=starts_with("gce") 为 true。
您可以在任何资源比较之前使用单个 NOT 运算符。例如，如果资源的区域不包括 "europe"，则 NOT resource.labels.zone:"europe" 为 true。您不能在带括号的表达式前使用 NOT。
您可以使用存在运算符 (:) 来测试密钥是否存在。例如，如果标签键 zone 在资源中存在，则比较 resource.labels.zone 为 true。

例如，虚拟机实例的一个平台资源元数据键是 spot_instance。以下过滤条件选择器选择的是 Spot 实例：

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

指标选择器

指标选择器通过限制指标类型和指标标签来指定特定指标或指标描述符。列出时间序列数据时，指标选择器必须指定单个指标类型：

<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>

例如，以下过滤条件可用于检索特定数据库实例的时间序列：

metric.type = "cloudsql.googleapis.com/database/state" AND
  (metric.labels.resource_type = "instance" AND
   metric.labels.resource_id = "abc-123456")

示例

在过滤示例中，我们使用以下指标描述符、受监控的资源描述符和虚拟机实例，并进行了简化说明：

# 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"

要优化请求，以仅针对每个实例上称为“log_partition”的磁盘设备查询读取带宽，请按如下所示定义过滤条件。此过滤条件针对每个实例最多返回一个时间序列，具体取决于该实例上是否存在同名设备：

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

要将请求限制为仅一个实例，请指定该实例：

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"

按组进行过滤

以下示例演示了如何在过滤条件中使用组选择器，将受监控的资源限制为特定组中的资源。如需了解用于定义组成员资格的选择器，请参阅组定义。

{ "name": "projects/my-test-project/groups/024681012",
  "display_name": "My Redis Cluster",
  "filter": "metadata.user_labels.role=redis" }

在对 projects.timeSeries.list 方法的调用中，以下过滤条件请求特定组中所有 Compute Engine 实例的磁盘读取带宽用量。必须在方法的 name 参数中指定的工作区中定义该组：

resource.type = "gce_instance" AND
group.id = "024681012" AND
metric.type = "compute.googleapis.com/instance/disk/read_bytes_count"