创建并管理变量和固定的过滤条件

使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

本文档介绍了如何固定信息中心级过滤条件，使这些过滤条件永久有效。固定的过滤条件可让您修改信息中心显示的数据，而无需修改每个 widget，它们具有默认状态，并应用于整个信息中心。信息中心工具栏会显示每个固定的过滤条件，以及一个菜单，您可以通过该菜单临时更改过滤条件的值。

变量与固定的过滤条件类似，但仅应用于特定 widget。本文档介绍了如何创建变量以及如何将其应用于 widget。变量可以修改 widget 的查询，也可以控制 widget 的可见性。信息中心工具栏会按名称显示每个变量，以及一个菜单，您可以通过该菜单临时更改变量的值。为了帮助您区分过滤条件和变量，在工具栏中，变量名称前面会附加美元符号 $。

本文档介绍如何使用 Google Cloud 控制台创建变量和固定的过滤条件。如需了解如何使用 Cloud Monitoring API，请参阅通过 API 创建和管理信息中心：信息中心过滤条件。

如需了解如何添加和修改仅应用于当前会话的临时分组和过滤条件，请参阅向自定义信息中心添加临时过滤条件。

只有 Google Cloud 项目支持此功能。对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。

固定的过滤条件简介

固定的过滤条件包含标签、一个或多个默认值以及所有可能的值列表。所有可能值的列表是从信息中心中显示的时序数据动态派生而来的。如需了解过滤条件的结构，请参阅 DashboardFilter。

您无法对各个 widget 应用固定的过滤条件。而是使用以下规则来确定固定的过滤条件能否更改 widget 显示的数据：

• 如果 widget 显示的数据包含由固定的过滤条件指定的标签键，并且如果 widget 没有为该标签键指定值，则固定的过滤条件可以更改显示的数据。

  例如，假设您添加了固定的过滤条件 cluster_name: mycluster。然后，图表会自动仅显示具有 cluster_name 标签且值为 mycluster 的时序。同样，日志面板 widget 上的查询会被修改为 resource.labels."cluster_name"="mycluster"，并且图表会自动仅显示固定过滤条件中包含该标签的时序。

• 如果某个 widget 包含针对同一标签键的过滤条件，或者该 widget 显示的数据不包含在固定的过滤条件中指定的标签键，则该 widget 会忽略固定的过滤条件。

变量简介

变量包含名称和类型。变量通过修改特定 widget 包含的查询来应用于该 widget。如需了解过滤条件的结构，请参阅 DashboardFilter。

在信息中心工具栏中，变量名称前面会附加美元符号 $。如果您还看到 visibility 可见图标，则表示变量控制至少一个 widget 的可见性。

变量可以基于标签，也可以仅具有一个值：

• 基于标签的变量类似于固定的过滤条件。这些变量包含标签键、一个或多个默认标签值以及所有可能的标签值列表。所有可能值的列表是从信息中心中显示的时序数据动态派生而来的。

• 仅包含值的变量包含一个或多个默认值，并且可能会列出所有可能的值。如果您未指定默认值，系统会为默认值选择通配符运算符 (*)。如需定义所有可能的值集合，您可以提供值数组或编写 SQL 查询。

  仅包含值的变量有三种类型：自定义、文本输入和 SQL 查询。

  • 自定义：如果您想要枚举所有可能的值列表，同时设置一个或多个默认值，请使用此选项。例如，您可以将所有可能的值列表设置为 prod, staging, dev，并将默认值设置为 prod。

  • 文本输入：如果您不知道所有可能的值，请使用此选项。例如，您可能希望按网址过滤，但在创建变量时，您不知道确切的网址列表。接着，当您将过滤条件菜单用于 widget 时，可以输入新网址，然后保存对当前会话或变量定义的更改。

  • SQL 查询：如果您想要使用 SQL 查询生成可能的值列表，请使用此选项。这些变量旨在应用于使用 Log Analytics 创建的图表。

    对于这些变量，请确保查询结果是一个表，该表包含一列，该列的数据类型为字符串，并且表中的每一行都包含唯一的字符串值：

    SELECT log_name
    FROM `TABLE_NAME_OF_LOG_VIEW`
    GROUP BY log_name
    

    该变量应查询与图表相同的表。

如需将变量应用于 widget，您可以更新该 widget 发出的查询，也可以更新该 widget 的可见性。您可以随时修改该 widget 以更新其查询。但是，对于基于标签的变量和某些 widget 类型，您可以通过进行菜单选择来更新查询。如需控制可见性，您必须修改 widget。如需了解详情，请参阅本文档的以下部分：

• 更新 widget 的查询
• 设置 widget 的可见性

准备工作

对于您要在其中配置过滤条件和变量的 Google Cloud 项目，请完成以下操作：

• 如需获得使用 Google Cloud 控制台添加或修改变量或固定的过滤条件所需的权限，请让您的管理员为您授予项目的 Monitoring Editor (roles/monitoring.editor) IAM 角色。如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

  您也可以通过自定义角色或其他预定义角色来获取所需的权限。

  如需详细了解角色，请参阅使用 Identity and Access Management 控制访问权限。

创建并固定过滤条件

如需创建并固定过滤条件以应用于支持过滤条件的所有信息中心 widget，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
3. 选择一个信息中心，前往信息中心工具栏，然后点击 settings 设置。
4. 在过滤部分，点击添加过滤条件 (Add a filter)。
5. 点击 arrow_drop_down 标签，然后选择一个标签。例如，您可以选择 zone。
6. 如需允许用户从变量的值菜单中选择多个值，请选择多选。如果未启用多选，用户只能从值菜单中选择一个选项。

7. 点击 arrow_drop_down 默认值，然后为标签选择一个或多个默认值。如需匹配所有值，请选择 *。

   创建过滤条件后，系统会将其添加到信息中心工具栏中。如需临时更改过滤条件值，请选择过滤条件，然后从菜单中进行选择。

8. 点击完成，然后点击应用。

9. 如需保存修改后的信息中心，请在工具栏中点击保存。

创建变量

如需创建应用于特定信息中心 widget 的变量，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
3. 选择一个信息中心，前往信息中心工具栏，然后点击 settings 设置。
4. 在变量部分中，点击添加变量。

5. 选择变量类型，然后完成对话框。

   如需创建基于标签的变量，请选择标签。如果您希望变量具有标签键和标签值，并且可以像过滤条件一样使用，请使用此选项。所有可能值的列表是从信息中心中显示的时序数据动态派生而来的。借助应用于图表菜单，您可以选择要由变量修改其查询的 widget。您还可以通过修改 widget 来更新查询。

   对于仅包含值的变量，您可以使用以下选项：

   • SQL：如果您希望 SQL 查询的结果生成所有可能的值列表，请使用此选项。

     输入一个或多个默认值，并输入 SQL 查询以生成所有可能的值列表。确保查询结果是一个表，该表包含一列，该列的数据类型为字符串，并且表中的每一行都包含唯一的字符串值：

   • 自定义：如果您想要同时指定可能的值列表和默认值，请使用此选项。例如，您可以将值字段设置为 prod, staging, dev，并将默认值设置为 prod。

   • 文本输入：如果您想要指定作为默认值应用的值列表，请使用此选项。

6. 点击完成，然后点击应用。

7. 如需保存修改后的信息中心，请在工具栏中点击保存。

8. 将该变量应用于 widget。如果您更新 widget 的查询，则当您更改变量的值时，查询会被修改，并且 widget 显示的数据也会被修改。您还可以使用变量来控制 widget 是否可见。如需了解详情，请参阅本文档中的以下部分：

   • 设置 widget 的可见性
   • 更新 widget 的查询

设置 widget 的可见性

在 widget 查询数据时，您可以使用变量来控制该 widget 是否在信息中心中可见。例如，假设一个信息中心包含显示生产系统数据的 widget，以及另一组显示预演系统数据的 widget。在开发期间进行调试时，您可能只想查看暂存数据。通过使用变量配置信息中心 widget 的可见性，您可以在仅显示生产数据、仅显示预演数据和显示所有数据之间切换。

任何类型的变量都可以控制 widget 是可见还是隐藏。

如需配置 widget 的可见性，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 选择一个信息中心。
3. 前往您要配置其可见性的 widget 的工具栏，然后点击 edit 修改。
4. 在显示窗格中，展开 Widget 可见性。

5. 选择一个变量并完成对话框。

6. 点击完成，然后点击应用。

7. 如需保存修改后的信息中心，请在工具栏中点击保存。

   信息中心会刷新。如果信息中心中至少一个 widget 因可见性控制而被隐藏，信息中心会显示一个横幅。如需查看所有 widget，请点击显示所有 widget。

当您使用变量来控制信息中心中至少一个 widget 的可见性时，在工具栏中，变量名称会使用 visibility 可见图标进行注解。

限制

在配置 widget 的可见性时，存在以下限制：

• 可收起组、部分标题和单视图 widget 等组织 widget 始终可见。

• 您可以删除由 widget 的可见性控制引用的变量。变量删除操作还会移除对该变量的任何引用。

• 并非所有信息中心都支持创建变量。但是，如果信息中心包含变量，则您可以使用这些变量来管理 widget 在信息中心中的可见性。

更新 widget 的查询

本部分介绍了如何在 widget 发出的查询中包含变量。因此，当您更改变量的值时，查询会被修改，并且 widget 显示的数据也会被修改：

• 对于使用 SQL、PromQL 或 MQL 查询的图表，以及对于日志面板 widget，您必须修改 widget 并修改查询。本部分介绍了如何进行这些修改。

• 对于您使用菜单或使用直接过滤模式配置的图表，当您使用应用于图表菜单选择 widget 时，Monitoring 会修改查询。作为替代方案，您也可以修改 widget，前往过滤条件字段，然后选择变量。

如需了解如何使用基于标签的变量或仅包含值的变量更新 widget 的查询，请参阅以下部分：

• 取消引用变量的一般语法
• 日志面板 widget
• 包含 PromQL 查询的图表
• 包含 SQL 查询的图表
• 包含 MQL 查询的图表

• 包含 Monitoring 过滤条件查询的图表

  当您使用菜单驱动的界面创建显示时序数据的图表时，您的选择会转换为 Monitoring 过滤条件。

创建过滤条件和变量

{
  "dashboardFilters": [
      {
        "labelKey": "zone"
        "stringValue": "us-central1-c",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL"
      },
      {
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "valueType": "STRING",
        "filterType": "RESOURCE_LABEL",
        "templateVariable": "my_label_based_variable"
      },
      {
        "filterType": "VALUE_ONLY",
        "templateVariable": "my_value_only_variable",
        timeSeriesQuery: {
          opsAnalyticsQuery: {
            sql: "
              SELECT log_name
              FROM `MY_TABLE`
              GROUP BY log_name
            ",
          }
        }
      }
    ],
  "displayName": "Illustrate Variables",
  ...
}

取消引用变量的一般语法

对于所有 widget（由 SQL 定义的 widget 除外），请使用以下语法将变量应用于查询：

• 如需应用基于标签的变量，并将标签键和标签值解析为查询语言的有效过滤表达式，请使用 ${my_label_based_variable}。

• 如需仅应用基于标签的变量的值，请使用 ${my_label_based_variable.value}。比较必须使用正则表达式。

• 如需仅应用仅包含值的变量的值，请使用 ${my_value_only_variable}。对于仅包含值的变量，请勿添加 .value 子句。比较必须使用正则表达式。

日志面板 widget

如需将变量应用于日志面板 widget，请更新查询窗格。这些 widget 的语法遵循一般语法下指定的语法。

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"

severity =~ "${value_only_severity_variable}"

severity =~ "^(ERROR|INFO|NOTICE)$"

"logsPanel": {
  "filter": "${my_label_based_variable}",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id=~\"${my_label_based_variable.value}\"\n",
  "resourceNames": [
    "projects/012345"
  ]
}

"logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
}

severity =~ "^(ERROR|INFO|NOTICE)$"

如果您已为日志面板配置查询，然后选择相应按钮以打开 Logs Explorer，则系统会在打开 Logs Explorer 之前解析变量。

下表说明了日志面板如何解析示例变量。如前所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

包含 PromQL 查询的图表

如需更新包含 PromQL 查询的图表，使其依赖于基于标签的变量，请按照一般语法中列出的指导操作。

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} }

compute_googleapis_com:instance_cpu_utilization{
    instance_id=~"${my_label_based_variable.value}"
}

zone=~"${my_value_only_variable}"

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\",
      ${my_label_based_variable}
      }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
    monitored_resource=\"gce_instance\",
    instance_id=~\"${my_label_based_variable.value}\"
    }[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

zone=~\"${my_value_only_variable}\"

下表说明了 PromQL 如何解析示例变量。如前所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

包含 SQL 查询的图表

如果您想更新 SQL 定义的 widget，使其依赖于变量，请更新 WHERE 子句以引用该变量的值。对于所有变量，请使用“at”符号作为变量名称的前缀，例如：@variable_name。对于基于标签的变量，请在变量名称后附加 .value (@my_label_based_variabe.value)。

对于 SQL 查询，变量替换依赖于 BigQuery，并且不会受到 SQL 注入的影响。如需了解详情，请参阅运行参数化查询。

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)

"plotType": "STACKED_BAR",
"targetAxis": "Y1",
"timeSeriesQuery": {
  "opsAnalyticsQuery": {
    "queryExecutionRules": {},
    "queryHandle": "",
    "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n
            FROM\n `my-project.global._Default._Default`\n
            WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000"
  }
}

"dashboardFilters": [
  {
    "filterType": "VALUE_ONLY",
    "templateVariable": "LogName",
    "valueType": "STRING",
    "timeSeriesQuery": {
      "opsAnalyticsQuery": {
        "savedQueryId": "",
        "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000",
        "queryHandle": ""
      },
      "unitOverride": "",
      "outputFullDuration": false
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

包含 MQL 查询的图表

如需更新包含 MQL 查询的图表以使用基于标签的变量，请附加一个竖线符 (|)，然后按照一般语法中列出的指导操作。

当您使用菜单驱动的界面创建显示时序数据的图表时，您的选择会转换为 Monitoring 过滤条件

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| every 1m
| ${my_label_based_variable}

fetch gce_instance
| metric 'compute.googleapis.com/instance/cpu/utilization'
| filter resource.instance_id=~'${my_label_based_variable.value}'
| group_by 1m, [value_utilization_mean: mean(value.utilization)]
| every 1m

resource.zone=~'${my_value_only_variable}'

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n
    | ${my_label_based_variable}",
  "unitOverride": "",
  "outputFullDuration": false
},

"timeSeriesQuery": {
  "timeSeriesQueryLanguage": "fetch gce_instance\n
    | metric 'compute.googleapis.com/instance/cpu/utilization'\n
    | filter resource.instance_id=~'${my_label_based_variable.value}'\n
    | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n
    | every 1m\n",
  "unitOverride": "",
  "outputFullDuration": false
},

resource.zone=~'${my_value_only_variable}'

下表说明了 MQL 如何解析示例变量。如前所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

包含 Monitoring 过滤条件查询的图表

如需更新包含采用 Monitoring 过滤条件形式的查询的图表，使其依赖于基于标签的变量，请按照一般语法中列出的指导操作。

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable}"

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})

"timeSeriesQuery": {
  "timeSeriesFilter": {
    "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
               resource.type=\"gce_instance\"
               ${my_label_based_variable} ",
    "aggregation": {
      "alignmentPeriod": "60s",
      "perSeriesAligner": "ALIGN_MEAN",
      "groupByFields": []
    }
  },
  "unitOverride": "",
  "outputFullDuration": false
},

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
          resource.type=\"gce_instance\"
          resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"

下表说明了 Monitoring 过滤条件如何解析示例变量。如前所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

修改固定的过滤条件或变量

如需临时更改信息中心工具栏中显示的任何过滤条件的值，请点击过滤条件名称，然后输入值或从菜单中进行选择。

如果信息中心包含显示时序数据的表，则您可以使用单元的 filter_list 按照此值过滤信息中心按钮来添加临时过滤条件或修改永久过滤条件和变量。选中此按钮后，系统会应用新的临时过滤条件，或更新现有过滤条件或变量的值。当表列的标签键与过滤条件或变量的标签键匹配时，系统会更新现有过滤条件和变量。

如需更改固定的过滤条件或变量的配置，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
3. 在信息中心工具栏中，点击 settings 设置。
4. 找到您要修改的过滤条件或变量，然后展开其定义。
5. 完成修改后，点击应用。
6. 如需保存修改后的信息中心，请在工具栏中点击保存。

删除固定的过滤条件或变量

如需删除固定的过滤条件或变量，请执行以下操作：

1. 在 Google Cloud 控制台中，转到 信息中心页面：

   前往信息中心

   如果您使用搜索栏查找此页面，请选择子标题为监控的结果。

2. 在 Google Cloud 控制台的工具栏中，选择您的 Google Cloud 项目。 对于 App Hub 配置，请选择 App Hub 宿主项目或已启用应用的文件夹的管理项目。
3. 在信息中心工具栏中，点击 settings 设置。
4. 找到您要移除的过滤条件或变量，然后点击 delete 删除。
5. 点击应用。
6. 如需保存修改后的信息中心，请在工具栏中点击保存。

后续步骤

• 研究已绘制成图表的数据
• 访问特定于资源的信息中心