本指南将介绍如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件来指定受监控的资源、指标类型、组定义和时序。
您还可以使用过滤条件来配置提醒政策,以监控系统上运行的进程。如需了解这些过滤条件,请参阅进程运行状况过滤条件。
准备工作
如果您不熟悉指标、时序和受监控的资源,请参阅指标、时序和资源。
如果您不熟悉标签,请参阅标签。
使用过滤器
您可以使用 Monitoring API 中的过滤器来执行以下操作:
选择从
list
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 选择器 |
---|---|---|---|---|
定义组 | 是 | 是1 | ||
列出群组成员 | 是 | 是 | ||
列出时序 | 是 | 是 | 是 | 是2 |
列出指标描述符 | 是 | 是 | ||
列出受监控的资源描述符 | 是 |
以下部分显示了监控过滤条件的典型用法示例。有关可用过滤条件对象和运算符的完整讨论,请参阅过滤条件语法。
检索时序数据
方法: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
,但不能在存在运算符 (:
) 或带英文括号的表达式之前使用:
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>
语法的扩展:
您可以根据元数据系统标签
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
指标选择器
指标选择器通过限制指标类型和指标标签来指定特定指标或指标描述符。列出时序数据时,指标选择器必须指定单个指标类型:
<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"