使用 API 创建和管理信息中心

本文档介绍了如何使用 Cloud Monitoring API 中的 Dashboard 资源创建和管理自定义信息中心以及这些信息中心中的微件。以下示例展示了如何使用 curl 调用 API 来管理信息中心，以及如何使用 Google Cloud CLI。虽然您也可以通过 Google Cloud 控制台管理自定义信息中心，但 API 为您提供了同时管理多个信息中心的程序化方式。

该端点支持以下方法来管理和配置信息中心：

您可以使用 curl 实用程序或使用 Google Cloud CLI 直接调用 API。

您无法检索、修改或删除预定义的信息中心。

信息中心简介

创建信息中心时，您必须指定要显示的组件或微件，以及这些微件的布局。您还可以向信息中心添加标签和过滤条件。标签可帮助您查找信息中心，或指明信息中心中的内容类型。

信息中心布局

布局定义了信息中心组件的排序方式。该 API 提供以下布局：

  • GridLayout：将可用空间划分为宽度相等的纵向列，并使用行优先策略排列一组微件。

  • MosaicLayout：将可用空间划分为网格。每个微件可以占据一个或多个网格块。

  • RowLayout：将可用空间划分为几行，并在每行中水平排列一组微件。

  • ColumnLayout：将可用空间划分为垂直列，并在每列中垂直排列一组微件。

例如，下图显示了 RowLayout 信息中心的 JSON 表示法，其中有三个 Text 微件：

{
  "displayName": "Row-layout example",
  "rowLayout": {
    "rows": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  }
}

信息中心微件

微件包含单个信息中心组件以及如何在信息中心中呈现组件的配置。一个信息中心可以有多个微件。Widget 对象有多种类型：

  • XyChart 微件会沿 X 轴和 Y 轴显示数据。

    此微件会显示数据集，该数据集可以是时间序列数据，也可以由 SQL 查询生成。借助此 widget，您可以将图表数据与左侧或右侧 Y 轴相关联。绘制多个指标类型的图表时，您可以使用两个 Y 轴。XyChart 微件支持以下显示样式：

    • 折线图
    • 条形图
    • 堆积面积图
    • 热图

  • 从一个维度显示数据的微件，例如最新值：

    • PieChart：显示一组时序的最新值，其中每个时序对应于一个饼状图 slice。

    • Scorecard：显示一组时序的最新值，以及该值与一个或多个阈值的关系。

    • TimeSeriesTable：显示每个时序的最新值或汇总值。表格支持自定义。例如，您可以为单元格设置颜色代码，并配置列名称和数据对齐方式。

  • 用于显示提醒政策或突发事件信息的微件：

    • AlertChart：显示单一条件提醒政策的摘要。此微件以折线图的形式显示数据，并显示阈值及列出未结突发事件的数量。

    • IncidentList：显示突发事件列表。您可以将该微件配置为显示特定提醒政策或特定资源类型的突发事件。

  • 用于显示日志条目和错误的微件：

  • 文本和组织微件：

    • CollapsibleGroup：显示一组微件。您可以收起某个群组的视图。

    • SingleViewGroup：在微件集合中显示一个微件。您可以选择要显示哪些微件。

    • SectionHeader：在信息中心内创建横向分隔线，并在信息中心的目录中创建条目。

    • Text：以原文或 Markdown 字符串的形式显示文字内容。

    如需在信息中心中添加文本和组织微件，该信息中心必须包含 MosaicLayout。

除了这些对象之外，您还可以向信息中心添加空白占位符。

例如，下面显示了配置右侧 Y 轴的 XyChart 微件的 JSON 表示法：

{
  "displayName": "Demo dashboard",
  "gridLayout": {
    "widgets": [
      {
        "title": "Sample line chart",
        "xyChart": {
          "dataSets": [
            {
              "timeSeriesQuery": {
                "timeSeriesFilter": {
                  "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
                  "aggregation": {
                    "perSeriesAligner": "ALIGN_MEAN",
                    "crossSeriesReducer": "REDUCE_MAX",
                    "groupByFields": [
                      "resource.label.zone"
                    ]
                  }
                },
                "unitOverride": "1"
              },
              "plotType": "LINE"
            }
          ],
          "timeshiftDuration": "0s",
          "yAxis": {
            "label": "y1Axis",
            "scale": "LINEAR"
          },
          "chartOptions": {
            "mode": "COLOR"
          }
        }
      }
    ]
  }
}

信息中心标签

标签可帮助您管理和整理信息中心。例如，您可以添加名为 prod 的标签，以指明信息中心会显示生产资源的时间序列数据和日志数据。或者，您也可以添加标签 playbook，以指明信息中心包含有助于您排查失败问题的信息。

向信息中心添加标签是可选操作。

例如，以下代码展示了一个 Dashboard 对象，用于指定名为 playbook 的标签。

{
  "displayName": "Example",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      ...
    ]
  },
  "dashboardFilters": [],
  "labels": {
    "playbook": ""
  }
}

如前面的示例所示，labels 字段实现为 map，其中 key 和 value 字段均为字符串。向信息中心添加标签时，请将 key 设置为标签的名称，并将 value 字段设置为空字符串。

信息中心过滤条件和变量

在设计信息中心时，您可以确定多种查看信息中心显示的数据的方式。例如，假设信息中心显示虚拟机 (VM) 实例的时间序列数据。您可能希望查看所有虚拟机的时间序列数据，也可能只希望查看特定可用区中的数据。在这种情况下，我们建议您创建一个固定的过滤条件或变量，然后将该过滤条件的默认值设置为最常查看的区域。

固定的过滤条件会应用于支持过滤条件中指定的标签的所有信息中心微件，除非该微件包含具有相同标签键的过滤条件。例如，当图表包含过滤条件 zone = us-central1-a 时，该图表会忽略标签键为 zone 的固定过滤条件。同样，如果图表中没有键为 zone 的标签，则会忽略此过滤条件。

变量类似于固定的过滤条件，但仅适用于特定 widget。变量可以基于标签（例如固定的过滤条件），也可以仅包含值。仅值变量包含一个或多个默认值，以及所有可能值的列表。如果您未指定默认值，则默认值会设为通配符运算符 (*)。如需定义一组所有可能的值，您可以提供一个值数组，也可以编写 SQL 查询。

对于固定的过滤条件和变量，信息中心工具栏会显示每个变量以及一个菜单，您可以通过该菜单临时更改变量的值。相同的数据结构用于表示固定的过滤条件和变量。如需了解详情，请参阅 DashboardFilter。

如需了解如何将基于标签的变量或仅值变量应用于 widget，请参阅以下部分：

创建过滤条件和变量

控制台

如需了解如何使用 Google Cloud 控制台创建固定的过滤条件和变量，请参阅以下文档：

API

如需定义固定的过滤条件和变量，请使用 dashboardFilters 数据结构。

  • 如需创建变量，请将 templateVariable 字段的值设置为变量的名称。如果您要创建固定的过滤条件，请省略此字段或将值设置为空字符串。
  • 如需创建固定的过滤条件或基于标签的变量，您必须指定 labelKey 字段。如果您想要仅包含值的变量，请省略此字段。

  • 为过滤条件或变量设置默认值。此字段的配置决定了用户能否从值菜单中选择确切的一个选项，还是可以选择多个值。

    • 如需设置单个默认值并限制用户只能在值菜单中选择一个选项，请将 valueType 字段设置为 STRING，并设置 stringValue 字段：
    "valueType": "STRING",
"stringValue": "my-default-value",
    • 如需设置至少一个默认值，并允许用户在值菜单中选择多个选项，请将 valueType 字段设置为 STRING_ARRAY，并设置 stringArrayValue 字段。在以下示例中，有三个默认值。
    "valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},

  • 可选：如需指定仅值变量的所有可能值列表，请设置 stringArray 字段或 timeSeriesQuery 字段。如果您指定查询，则该查询必须是分析查询。

例如，请考虑以下 dashboardFilters 对象：

{
  "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",
  ...
}

上一个 JSON 定义了一个固定的过滤条件和两个变量：

  • 已固定的过滤条件的标签键为 zone，该键会显示在工具栏上。valueType 和 stringValue 字段用于指定单个默认值。如需了解详情，请参阅 dashboardFilters 数据结构的 API 参考文档页面。

  • 基于标签的变量名为 my_label_based_variable，其标签键为 instance_id。此变量的默认值设为特定实例 ID。您还可以使用数组配置默认值。在工具栏上，过滤器显示为名称为 my_label_based_variable 的过滤器。

  • 仅包含值的变量名为 my_value_only_variable。此条目未指定默认值，因此系统会自动应用通配符运算符 (*)。此外，此变量还使用 SQL 查询生成该变量的可能值列表。

请注意，dashboardFilters 对象不会列出应用了该变量的微件。如需将变量应用于 widget，您可以修改 widget 的查询。

解引用变量的一般语法

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

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

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

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

日志面板微件

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

控制台

例如，以下查询使用正则表达式将 jsonPayload.message 字段的值与包含基于标签的变量值的字符串值进行比较：

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

再举一个例子，假设有一个仅包含值的变量 value_only_severity_variable，并且在值菜单中选择了三个值：ERROR、INFO 和 NOTICE。接下来，将以下代码添加到日志面板 widget 的查询窗格中：

severity =~ "${value_only_severity_variable}"

下图展示了呈现的形式：

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

API

例如，以下 JSON 展示了如何将基于标签的变量应用于日志面板微件的查询：

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

例如，以下查询使用正则表达式将 jsonPayload.message 字段的值与包含基于标签的变量值的字符串值进行比较：

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

再举一个例子，假设有一个仅包含值的变量 value_only_severity_variable，并且在菜单中选择了三个值：ERROR、INFO 和 NOTICE。接下来，将以下代码添加到日志面板 widget 的查询窗格中：

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

以下示例展示了日志面板 widget 执行的查询：

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

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

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

语法 已选
值		 已解析的日志面板表达式
${my_label_based_variable} 12345 resource.labels."instance_id"="12345"

示例变量基于资源标签 instance_id。
${my_label_based_variable} * ""
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

包含 PromQL 查询的图表

如需将基于标签的变量应用于包含 PromQL 查询的图表，请按照常规语法中列出的指南操作。

控制台

例如，以下查询依赖于基于标签的变量 my_label_based_variable 解析为过滤条件表达式：

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

您还可以修改查询，以便仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

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

如果您使用的是仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

zone=~"${my_value_only_variable}"

API

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_variable 解析为过滤表达式：

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

您还可以修改查询，以便仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

"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
},

如果您使用的是仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

zone=~\"${my_value_only_variable}\"

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

语法 已选
值		 已解析的 PromQL 表达式
${my_label_based_variable} 12345 instance_id == '12345'

示例变量基于资源标签 instance_id。
${my_label_based_variable} * noop_filter=~".*"
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .+

包含 SQL 查询的图表

如需将变量应用于 SQL 定义的 widget，请更新 WHERE 子句以引用变量的值。对于所有变量，请在变量名称前面加上“at”符号，例如：@variable_name。对于基于标签的变量，请将 .value 附加到变量名称 @my_label_based_variabe.value。

对于 SQL 查询，变量替换依赖于 BigQuery，并且可以防止 SQL 注入。如需了解详情，请参阅运行参数化查询。

控制台

由于 SQL 不会将通配符运算符解释为“任何值”，因此我们建议您在将变量应用于 SQL 查询时始终使用 IF 语句。以下示例展示了数据类型为字符串的仅值变量的用法：

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

如果变量的菜单选项允许用户选择多个值，您必须使用 CAST 函数将变量的值转换为 GoogleSQL 数据类型。以下查询展示了此语法：

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

建议使用前面示例中显示的 IF 语句，因为 SQL 不会将通配符运算符解读为“任何值”。因此，如果您省略 IF 语句并选择通配符运算符，则查询结果将为空表。在第二个示例中，UNNEST 函数会将数组转换为表格。

如需添加格式正确的 WHERE 子句，请执行以下操作：

  1. 修改微件。
  2. 在工具栏中，选择插入变量过滤条件，然后选择要应用于 WHERE 子句的变量。
  3. 在打开的对话框中，查看生成的代码，然后点击复制并关闭。

  4. 将复制的代码粘贴到查询窗格中，然后进行必要的修改。

    例如，假设您创建了一个名为 LogName 的变量，用于生成日志名称列表，并将结果输出到一个包含一个名为 log_name 的列的表中。接下来，您需要创建一个图表，选择插入变量过滤器，然后选择变量 LogName。系统会生成以下代码：

    WHERE IF(@LogName = '*', TRUE, LogName = @LogName)

    在此示例中，您需要修改生成的代码，并将 LogName = 替换为 log_name =，以便执行表联接：

    WHERE IF(@LogName = '*', TRUE, log_name = @LogName)

  5. 依次点击运行和应用。

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

API

由于 SQL 不会将通配符运算符解释为“任何值”，因此我们建议您在将变量应用于 SQL 查询时始终使用 IF 语句。以下示例展示了数据类型为字符串的仅值变量的用法：

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

例如，以下是显示 SQL 查询结果的图表的部分 JSON 表示法。为了支持按日志名称过滤结果，添加了一个引用名为 LogName 的变量的 WHERE 子句：

"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"
  }
}

变量 LogName 还会发出查询，以确定可能的日志名称列表：

"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
    }
  }
],

如果变量的菜单选项允许用户选择多个值，您必须使用 CAST 函数将变量的值转换为 GoogleSQL 数据类型。以下查询展示了此语法：

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

建议使用前面示例中显示的 IF 语句，因为 SQL 不会将通配符运算符解读为“任何值”。因此，如果您省略 IF 语句并选择通配符运算符，则查询结果将为空表。在第二个示例中，UNNEST 函数会将数组转换为表格。

使用 MQL 查询的图表

如需将基于标签的变量应用于包含 MQL 查询的图表，请附加一个管道符 (|)，然后按照一般语法中列出的指南操作。

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

控制台

例如，以下查询依赖于基于标签的变量 my_label_based_variable 解析为过滤条件表达式：

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

您还可以修改查询，以便仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

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

如果您使用的是仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

resource.zone=~'${my_value_only_variable}'

API

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_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
},

您还可以修改查询，以便仅解析变量的值。以下示例使用正则表达式将基于标签的查询的值与 instance_id 进行比较：

"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
},

如果您使用的是仅包含值的变量，请省略 .value 子句。例如，如需使用仅包含值的变量按可用区过滤，查询将包含如下内容：

resource.zone=~'${my_value_only_variable}'

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

语法 已选
值		 已解析的 MQL 表达式
${my_label_based_variable} 12345 filter (resource.instance_id == '12345')

示例变量基于资源标签 instance_id。
${my_label_based_variable} * filter (true)
${my_label_based_variable.value}
${my_value_based_variable}		 12345 12345
${my_label_based_variable.value}
${my_value_based_variable}		 * .*

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

如需将基于标签的变量应用于查询形式为监控过滤条件的图表，请遵循一般语法中列出的指南。

控制台

如果您使用 Google Cloud 控制台创建图表，并且使用的是菜单驱动型界面，则可以使用变量的应用于图表字段，或通过修改微件并从过滤菜单中选择基于标签的变量，将基于标签的变量应用于图表。过滤菜单会列出所有基于标签的变量和所有标签键。

如需将基于值的变量应用于这些类型的图表，请执行以下操作：

  1. 修改图表。
  2. 在“查询”窗格中，点击添加过滤条件，然后选择一个标签键。例如，您可以选择可用区。
  3. 在值菜单中，选择仅包含值的变量。
  4. 点击应用。
  5. 如需保存修改后的信息中心，请点击工具栏中的保存。

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_variable 解析为过滤表达式：

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

使用监控过滤条件形式的查询的微件无法按基于标签的变量中的值过滤时序；不过，您可以按仅包含值的变量进行过滤。例如，以下查询显示了按 zone 过滤的查询的 Filters 字段的值，该查询基于仅值变量的值进行过滤：

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

API

例如，以下 JSON 展示了一个查询，该查询依赖于基于标签的变量 my_label_based_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
},

使用监控过滤条件形式的查询的微件无法按基于标签的变量中的值过滤时序；不过，您可以按仅包含值的变量进行过滤。例如，以下查询会显示基于仅值变量的值按 zone 过滤的查询的 "filter" 字段：

"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 过滤器如何解析示例变量。如前所述，如果仅使用变量的值，则必须使用正则表达式作为比较运算符：

语法 已选
值		 已解析的过滤条件表达式
${my_label_based_variable} 12345 resource.instance_id == "12345"

示例变量基于资源标签 instance_id。
${my_label_based_variable} * 已忽略
${my_label_based_variable.value} 12345 不支持
${my_label_based_variable.value} * 不支持
${my_value_based_variable} 12345 "12345"
${my_value_based_variable} * ".*"

创建信息中心

如需创建新的自定义信息中心，请调用 dashboards.create 方法，并为其提供要显示在信息中心内的布局和微件。

创建信息中心时，API 会自动生成 dashboard_id。如果您要指定自定义 dashboard_id，可以设置 Dashboard 对象的 name 字段。名称字段的格式如下所示：

"name": "projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"

API

如需创建新的信息中心，请向Dashboard端点发送 POST 请求。

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

如需在项目中创建信息中心，请使用 gcloud monitoring dashboards create 命令。

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

例如，如果您要复制信息中心，请执行以下操作：

  1. 完成获取信息中心中的步骤，下载原始信息中心的定义。
  2. 修改返回的 JSON 以移除 etag 和 name 字段，并更改 displayName 字段的值。
  3. 运行该命令以创建信息中心。

如需了解详情，请参阅 gcloud monitoring dashboards create 参考文档。

Terraform

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

如需使用 Terraform 创建信息中心，请使用 Terraform 资源 google_monitoring_dashboard。

在该命令中，设置以下字段：

  • dashboard_json：信息中心的 JSON 表示法，采用 Dashboards 格式。

    如需查看此格式的示例，您可以使用 API Explorer 列出信息中心，也可以在 Google Cloud 控制台中打开信息中心，然后查看 JSON 表示法。

  • parent：项目的完全限定名称。例如，您可以将此字段设置为 "projects/PROJECT_ID"，其中 PROJECT_ID 是您的 Google Cloud 项目的 ID。

这些示例使用 my-dashboard.json 文件创建示例信息中心。 您可以通过 Google Cloud 控制台管理信息中心。

如需了解其他信息中心配置，请参阅示例信息中心和布局。

删除信息中心

如需删除自定义信息中心，请调用 dashboards.delete 方法并指定要删除的信息中心。

API

如需删除自定义信息中心，请向 Dashboard 端点发送一个 DELETE 请求，并使用要删除的信息中心的 ID 进行限定。

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

如果成功，该方法将返回一个空响应。否则，将返回错误。

gcloud

如需删除自定义信息中心，请使用 gcloud monitoring dashboards delete 并指定要删除的信息中心的完全限定 ID：

gcloud monitoring dashboards delete projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

如需了解详情，请参阅 gcloud monitoring dashboards delete 参考文档。

Terraform

您可以使用 Terraform 删除资源。如需了解如何删除资源，请参阅 Terraform 命令 destroy。

列出信息中心

如需列出属于某个项目的所有自定义信息中心，请调用 dashboards.list 方法并指定项目 ID。

API

要列出项目的所有自定义信息中心，请将项目 ID 发送到Dashboard端点。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

如需列出项目的所有自定义信息中心，请使用 gcloud monitoring dashboards list 命令：

gcloud monitoring dashboards list

如需了解详情，请参阅 gcloud monitoring dashboards list 参考文档。

Terraform

您无法使用 Terraform 向项目发送查询，并将信息中心列表作为响应。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

这些示例会返回与您的项目关联的自定义信息中心。

对列表响应进行分页

dashboards.list 方法支持分页功能，您可以一次获取一页结果，而不是一次获取所有结果。

API

对于结果列表的初始页面，请使用请求指定 pageSize 查询参数：

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

该方法返回列表的第一页和 nextPageToken。例如：

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

对于每个剩余信息页，您必须在请求中包含相应的 nextPageToken。

gcloud

如需指定每个页面的资源数量，请使用命令传递 --page-size 标记。例如：

gcloud monitoring dashboards list --page-size=1

Terraform

您无法使用 Terraform 向项目发送查询，并将响应作为信息中心的分页列表返回。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

获取信息中心

如需获取项目的特定自定义信息中心，请调用 dashboards.get 方法，并使用信息中心 ID 进行限定。

API

如需获取特定的自定义信息中心，请将信息中心 ID 发送到 Dashboard 端点。

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

该方法会返回类似于以下示例的响应：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

如需获取特定的自定义信息中心，请使用 gcloud monitoring dashboards describe 命令并指定信息中心 ID：

gcloud monitoring dashboards describe ${DASHBOARD_ID} --format=json

该命令会返回请求的信息中心：

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

如需了解详情，请参阅 gcloud monitoring dashboards describe 参考文档。

Terraform

您无法使用 Terraform 向项目发送查询，并将响应作为单个信息中心。不过，您可以使用 Google Cloud 控制台查看这些信息中心。

更新信息中心

如需更新现有的自定义信息中心，请调用 dashboards.patch 方法。如需获取当前的 etag 值，您可以调用 dashboards.get 方法并在响应中找到它。

API

要更新自定义信息中心，请将 PATCH 请求发送到 Dashboard 端点，并从最近的 dashboards.get 响应提供修改后的 Dashboard 对象和 etag 值。

curl -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/${DASHBOARD_ID}

上例使用 my-updated-dashboard.json 文件更新现有自定义信息中心。响应包含新的 etag 值，是更新后的信息中心列表的副本。

gcloud

如需更新自定义信息中心，请使用 gcloud monitoring dashboards update，指定要更新的信息中心的 ID，然后将更改提供给信息中心。

gcloud monitoring dashboards update ${DASHBOARD_ID} --config-from-file=my-updated-dashboard.json

如需了解详情，请参阅 gcloud monitoring dashboards update 参考文档。

上述示例使用 my-updated-dashboard.json 文件更新现有自定义信息中心。响应包含新的 etag 值，是更新后的信息中心列表的副本。

Terraform

如需了解如何应用或移除 Terraform 配置，请参阅基本 Terraform 命令。 如需了解详情，请参阅 Terraform 提供程序参考文档。

如需使用 Terraform 更新信息中心，请使用 Terraform 资源 google_monitoring_dashboard。

在该命令中，设置以下字段：

  • dashboard_json：信息中心的 JSON 表示法，采用 Dashboards 格式。

  • parent：项目的完全限定名称。例如，您可以将此字段设置为 "projects/PROJECT_ID"，其中 PROJECT_ID 是您的 Google Cloud 项目的 ID。

后续步骤