本指南介绍了如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件来指定受监控的资源、指标类型、组定义和时间序列。您还可以使用过滤器来配置提醒政策， 监控 如需了解这些过滤条件 请参阅进程运行状况过滤器。
准备工作
如果您不熟悉指标、时间序列和受监控的资源，请参阅指标、时间序列和资源。
如果您不熟悉标签，请参阅标签。
使用过滤器
您可以使用 Monitoring API 中的过滤器来执行以下操作：
列出特定指标类型。如需了解详情和示例，请参阅列出指标描述符。
列出特定的受监控资源类型。如需了解详情和示例，请参阅列出受监控的资源描述符。
过滤条件选择器
过滤条件至少包含一个选择器，即过滤条件关键字。以下示例演示了不同的选择器：
-
project：在name参数中提及的指标范围的限定范围中显示指定项目的指标时进行匹配。如果是 Google Cloud 项目，请使用
project选择器 可以查看多个 Google Cloud 项目或 AWS 账号的指标 而您只想查看单个项目的指标例如，如果 指标范围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"
从名称相同的 Compute Engine 实例返回所有时序 以
frontend-开头，请使用以下过滤条件：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]
一个组可以包含任意数量的资源（由过滤条件指定）。分组
成员资格是动态变化的每增加或减少 1 项资源可能就会符合该过滤条件
过滤器评估时间。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 选择器，则必须指定指标对于范围界定项目可见的项目。
- 返回属于某个 Pub/Sub 主题资源的所有 Pub/Sub 主题资源的列表，
项目
my-project，请使用以下过滤条件：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/instance/disk/read_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。例如，图表 以下选择器会显示所有虚拟机的 CPU 利用率 机器类型为e2-medium或e2-micro的实例：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” 存在运算符 (:) 或带圆括号的表达式。您可以使用“存在”运算符 (
:) 来测试是否存在键。 例如，如果标签为resource.labels:zone，则比较结果为 true。 资源中存在键zone。
例如，虚拟机实例的一个平台资源元数据键是 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")