监控过滤器

本指南将介绍如何在使用 Monitoring API 时配置过滤条件。您可以使用过滤条件来指定受监控的资源、指标类型和时序。

准备工作

如果您不熟悉指标、时序和受监控的资源，请参阅指标、时序和资源。

如果您不熟悉标签，请参阅标签。

使用过滤器

您可以使用 Monitoring API 中的过滤器来执行以下操作：

  • 选择从 list API 请求返回的特定时间序列数据。 过滤条件可以根据数据的受监控资源属性和指标属性选择时序。如需了解详情和示例，请参阅检索时间序列数据。

过滤条件选择器

过滤条件至少包含一个选择器，即过滤条件关键字。以下示例展示了不同的选择器：

  • resource：匹配特定类型或具有特定标签值的受监控资源。

    • 以下过滤条件匹配属于 Compute Engine 虚拟机 (VM) 实例的所有受监控资源：

      resource.type = "gce_instance"

  • 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 调用的过滤条件中允许哪些选择器：

过滤条件用途 resource 选择器 metric 选择器
列出时间序列 是 是 *
列出指标描述符 是
列出受监控的资源描述符 是
* 列出时序时，您必须仅指定一种指标类型。

以下部分显示了监控过滤条件的典型用法示例。有关可用过滤条件对象和运算符的完整讨论，请参阅过滤条件语法。

检索时间序列数据

方法：projects.timeSeries.list
过滤对象：project、resource.type、resource.labels.[KEY]、metric.type、metric.labels.[KEY]

时间序列是来自特定受监控的资源的指标类型时间戳数据点的列表。如需了解详情，请参阅指标模型。 指标类型由指标描述符指定，受监控的资源由受监控的资源描述符指定。

为 timeSeries.list 方法指定的过滤条件必须包含 metric 选择器，并且该选择器必须仅指定一种指标类型：

  • 返回特定指标类型的所有时序：
    metric.type = "compute.googleapis.com/instance/cpu/usage_time"

  • 如需返回特定 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.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"

参考：过滤条件语法

有关过滤条件的概览和示例，请参阅使用过滤条件。

监控过滤条件是一个字符串，最多包含两种类型的选择器：

    <monitoring_filter> ::= <resource_selector> AND
                             <metric_selector>

如果过滤条件包含的所有选择器都匹配某一项，则过滤条件匹配该项。 如以下部分所述，一些选择器可以通过 AND 或 OR 联接多项比较。选择器在过滤条件中的顺序无关紧要，但不同选择器的比较不得相互干扰。

根据过滤条件的用途，某些选择器可能是必需的、可选的或禁止的。例如，用于列出时序的过滤条件必须包含指标选择器。

比较

过滤条件及其选择器是通过比较构建的。每个比较都具有以下形式：

  • [OBJECT]：选择要测试的值，可以是以下项之一：

    metric.type
metric.labels.[KEY]
resource.type
resource.labels.[KEY]

    [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")

过滤条件选择器

使用选择器将过滤条件选择限制为特定项。在以下部分中，大括号用于显示重复。 例如，表示法 <x> {OR <y>} 表示您可以编写以下任何一项：

<x>
<x> OR <y>
<x> OR <y> OR <y>
<x> OR <y> OR <y> OR <y>
...

资源选择器

资源选择器将过滤条件选择限制为具有特定资源类型或标签值的资源（或与资源关联的项）：

<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>，请将它们用英文括号括起，以提高可读性。

指标选择器

指标选择器通过限制指标类型和指标标签来指定特定指标或指标描述符。与 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")