本指南介绍了如何在使用 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"
如需返回名称以
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]
一个组可以包含任意数量的资源（由过滤条件指定）。群成员资格是动态的；每次计算过滤条件时，可能有更多或更少的资源与该过滤条件匹配。指定群组和指标范围的范围项目metrics-scope-concept的 Group 对象的 name 参数。如果在过滤器中使用 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%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”运算符 (
:) 来测试密钥是否存在。例如，如果标签为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")