监控过滤条件

本指南将介绍如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件来指定受监控的资源、指标类型、组定义和时间序列。

准备工作

如果您不熟悉指标、时间序列和受监控的资源，请参阅指标、时间序列和资源。

如果您不熟悉标签，请参阅标签。

使用过滤器

您可以使用 Monitoring API 中的过滤器来执行以下操作：

选择从 list API 请求返回的特定时间序列数据。过滤条件可以根据数据的项目、组、受监控的资源和指标属性选择时间序列。如需了解详情和示例，请参阅检索时间序列数据。
根据资源的属性及其所属项目将资源分配给 Group。如需了解详情和示例，请参阅定义组成员资格。
根据资源的属性及其所属项目选择组内的资源。如需了解详情和示例，请参阅列出组成员。
列出特定指标类型。如需了解详情和示例，请参阅列出指标描述符。
列出特定的受监控资源类型。如需了解详情和示例，请参阅列出受监控的资源描述符。

过滤条件选择器

过滤条件至少包含一个选择器，即过滤条件关键字。以下简单示例演示了不同的选择器：

project：在 name 参数中提及的指标范围的限定范围中显示指定项目的指标时进行匹配。

如果 Google Cloud 项目可以查看多个 Google Cloud 项目或 AWS 帐号的指标，并且您只需要单个项目的指标，请使用 project 选择器。例如，如果 Project-A 的指标范围包括 Project-B，则当 name 的值为 Project-A 且您使用以下过滤条件时会出现匹配：
```
    project = "Project-B"
```
group：匹配属于一个 Group 的资源。
- 匹配标识符为 group-id 的群组：
```
group.id = "group-id"
```
resource：匹配特定类型或具有特定标签值的受监控的资源。
- 匹配属于 Compute Engine 虚拟机 (VM) 实例的所有受监控的资源：
```
resource.type = "gce_instance"
```
- 匹配地区以 europe- 开头的所有资源：
```
resource.labels.zone = starts_with("europe-")
```
metric：将特定指标类型或时间序列与具有与特定值匹配的特定标签相匹配。
- 与特定指标匹配：
```
metric.type = "compute.googleapis.com/instance/cpu/usage_time"
```
- 将时间序列与名为 instance_name 且值以 gke-hipster 或 gke-nginx 开头的标签的匹配：
```
metric.labels.instance_name = monitoring.regex.full_match("^gke-(hipster|nginx).*")
```

下表显示了基于 Monitoring API 调用的过滤条件中允许哪些选择器：

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

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

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

检索时间序列数据

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

时间序列是来自特定受监控的资源的指标类型时间戳数据点的列表。如需了解详情，请参阅指标模型。指标类型由指标描述符指定，受监控的资源由受监控的资源描述符指定。

在 list 命令中指定的过滤条件必须包含 metric 选择器，并且该选择器只能指定正好一种指标类型：

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

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

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

返回特定 Compute Engine 实例中的所有时间序列：

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

返回名称以 frontend- 开头的 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 虚拟机 (VM) 实例：

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 的所有 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

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

要仅检索 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"