本指南介绍了如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件来指定受监控的资源、指标类型、组定义和时序。您还可以使用过滤条件来配置提醒政策，以监控系统上运行的进程。如需了解这些过滤条件，请参阅进程运行状况过滤条件。
准备工作
如果您不熟悉指标、时序和受监控的资源，请参阅指标、时序和资源。
如果您不熟悉标签，请参阅标签。
使用过滤器
您可以使用 Monitoring API 中的过滤器来执行以下操作：
列出特定指标类型。如需了解详情和示例，请参阅列出指标描述符。
列出特定的受监控资源类型。如需了解详情和示例，请参阅列出受监控的资源描述符。
过滤条件选择器
过滤条件至少包含一个选择器，即过滤条件关键字。以下示例演示了不同的选择器：
-
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 调用的过滤条件中允许哪些选择器：
| 过滤条件用途 | project 选择器 |
group 选择器 |
resource 选择器 |
metric 选择器 |
|---|---|---|---|---|
| 定义组 | 是 | 是* | ||
| 列出群组成员 | 是 | 是 | ||
| 列出时间序列 | 是 | 是 | 是 | 是 † |
| 列出指标描述符 | 是 | 是 | ||
| 列出受监控的资源描述符 | 是 |
† 列出时序时，必须仅指定一种指标类型。
以下部分显示了监控过滤条件的典型用法示例。有关可用过滤条件对象和运算符的完整讨论，请参阅过滤条件语法。
检索时间序列数据
方法：projects.timeSeries.list
过滤对象：
project、group.id、resource.type、resource.labels.[KEY]、metric.type、
metric.labels.[KEY]
时间序列是来自特定受监控的资源的指标类型时间戳数据点的列表。如需了解详情，请参阅指标模型。指标类型由指标描述符指定，受监控的资源由受监控的资源描述符指定。
向 timeSeries.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 参数指定组和指标范围的范围项目metrics-scope-concept。如果在过滤条件中使用 project 选择器，则必须指定指标对于范围界定项目可见的项目。
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")
如需查看可用指标类型的完整列表，请参阅指标列表。如需简要了解指标的命名方式，请参阅指标命名惯例。
列出受监控的资源描述符
方法：projects.monitoredResourceDescriptors.list
过滤对象：resource.type
使用过滤条件限制要检索的受监控的资源描述符：
- 如需仅检索 Pub/Sub 受监控的资源描述符，请使用以下过滤条件：
resource.type = starts_with("pubsub")
如需查看由 Monitoring 定义的受监控的资源类型的完整列表，请参阅受监控的资源列表。
示例
在过滤示例中，我们使用以下指标描述符、受监控的资源描述符和虚拟机实例，并进行了简化说明：
# 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"
参考：过滤条件语法
有关过滤条件的概览和示例，请参阅使用过滤条件。
监控过滤条件是一个字符串，最多包含四种类型的选择器：
<monitoring_filter> ::= <project_selector> AND
<group_selector> AND
<resource_selector> AND
<metric_selector>
如果过滤条件包含的所有选择器都匹配某一项，则过滤条件匹配该项。如以下部分所述，一些选择器可以通过 AND 或 OR 联接多项比较。选择器在过滤条件中的顺序无关紧要，但不同选择器的比较不得相互干扰。
根据过滤条件的用途，某些选择器可能是必需的、可选的或禁止的。例如，用于列出时序的过滤条件必须包含指标选择器。 不过，用于定义组中资源的过滤条件不能包含指标选择器，因为组不包含指标类型或时序。
比较
过滤条件及其选择器是通过比较构建的。每个比较都具有以下形式：
-
[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，但不能在存在运算符 (:) 或带英文括号的表达式之前使用：
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> ')'
<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>}
如果您在选择器中使用多个 <r_label_comparison>，请将它们用括号括起，以提高可读性。例如，以下过滤条件可用于定义一个组，其中包含美国和欧洲的所有 Compute Engine 虚拟机实例。
resource.type = "gce_instance" AND
(resource.labels.zone = starts_with("us-") OR resource.labels.zone = starts_with("europe-"))
组定义的资源选择器
用于定义组成员资格的资源选择器使用 <resource_selector> 语法的扩展：
您可以根据元数据系统标签
metadata.system_labels.[KEY]和元数据用户标签metadata.user_labels.[KEYSTRING]的值添加过滤条件。我们建议为metadata.user_labels的键添加英文引号，因为它们可能包含连字符等特殊字符。如果选择器包含元数据过滤条件和资源过滤条件，您必须使用
AND将它们组合起来；不能使用OR。例如，如果图表包含以下选择器，则会显示机器类型为e2-medium或e2-micro的所有虚拟机实例的 CPU 利用率：metric.type="compute.googleapis.com/instance/cpu/utilization" resource.type="gce_instance" AND (metadata.system_labels."machine_type"="e2-medium" OR metadata.system_labels."machine_type"="e2-micro")
您可以使用不等于运算符 (
!=) 比较资源类型、资源标签和元数据。在比较字符串、数字、布尔值或子字符串函数时，可以使用该运算符。例如，如果资源类型不是以"gce"开头，则resource.type!=starts_with("gce")为 true。您可以在资源比较之前使用单个
NOT运算符。例如，如果资源的区域不包括"europe"，则NOT resource.labels.zone="europe"为 true。您不能在存在运算符 (:) 或带英文括号的表达式之前使用NOT。您可以使用“exists”运算符 (
:) 来测试密钥是否存在。例如，如果标签键zone在资源中存在，则比较resource.labels:zone为 true。
例如，虚拟机实例的一个平台资源元数据键是 spot_instance。以下过滤条件选择器选择的是 Spot 实例：
resource.type = "gce_instance" AND metadata.system_labels.spot_instance = true
指标选择器
指标选择器通过限制指标类型和指标标签来指定特定指标或指标描述符。与 projects.timeSeries.list 方法搭配使用时，指标选择器必须指定单个指标类型：
<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>}
例如，以下过滤条件可用于检索特定数据库实例的时间序列：
metric.type = "cloudsql.googleapis.com/database/state" AND (metric.labels.resource_type = "instance" AND metric.labels.resource_id = "abc-123456")