本指南将介绍如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件指定受监控的资源、指标类型、 组定义、 和时序。
您还可以使用过滤器来配置提醒政策，以监控系统上运行的进程。如需了解这些过滤器，请参阅进程运行状况过滤器。准备工作
如果您不熟悉指标、时序和受监控的资源，请参阅指标、时序和资源。
如果您不熟悉标签，请参阅标签。
使用过滤器
您可以使用 Monitoring API 中的过滤器来执行以下操作：
- 选择从
listAPI 请求返回的特定时序数据。该过滤器可以根据数据的项目、 组、 受监控的资源属性和指标属性选择时序。如需了解详情并查看示例，请参阅检索时序数据。 根据资源的属性及其所属项目选择组内的资源。如需了解详情和示例，请参阅列出群组成员。
列出特定指标类型。如需了解详情和示例，请参阅列出指标描述符。
列出特定的受监控资源类型。如需了解详情和示例，请参阅列出受监控的资源描述符。
过滤条件选择器
过滤条件至少包含一个选择器，即过滤条件关键字。以下示例展示了不同的选择器：
-
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 选择器，则必须指定一个项目，该项目的指标对限定范围的项目可见。
- 如需返回欧洲所有 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")
如需查看可用指标类型的完整列表，请参阅指标列表。如需简要了解指标的命名方式，请参阅指标命名惯例。
列出受监控的资源描述符
方法：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。您可以使用“存在”运算符 (
:) 测试密钥是否存在。例如，如果资源中存在标签键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")