按 API 创建和管理信息中心

本文档介绍了如何使用 Cloud Monitoring API 中的 Dashboard 资源创建和管理自定义信息中心以及这些信息中心上的微件。此处的示例说明了如何使用 curl 调用 API 来管理信息中心，还展示了如何使用 Google Cloud CLI。您还可以通过 Google Cloud 控制台管理自定义信息中心，但该 API 可让您以编程方式同时管理多个信息中心。

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

• dashboards.create：创建信息中心
• dashboards.delete：删除指定的信息中心
• dashboards.list：检索给定项目中所有信息中心的列表
• dashboards.get：检索指定的信息中心
• dashboards.patch：更新指定信息中心的结构

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

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

准备工作

创建信息中心时，您必须指定要显示的组件（即 widget）以及这些 widget 的布局。您还可以向信息中心添加永久性过滤条件。

信息中心布局

布局定义了信息中心组件的排序方式。该 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 轴显示数据。 以下图表是 XyChart widget 的实例：

  • 折线图

  • 条形图

  • 堆叠面积图

  • 热图

  • Log Analytics 图表

  • SLO 微件，但不支持使用 API 创建 SLO 图表。

  如果您创建折线图、堆叠条形图或堆叠面积图，则可以指定指标表示左侧或右侧 Y 轴。如果为多个指标绘制了图表，您可以同时使用两个 Y 轴。

  • PieChart：显示指标的最新值，其中每个时序对饼图做出一个切片。

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

  • TimeSeriesTable：显示指标的最新值。您可以根据列对表格进行排序、过滤表格或在显示结果中添加或移除列。

• 提醒图表和突发事件微件：

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

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

• 日志微件和错误微件：

  • ErrorReportingPanel：显示存储在所选 Google Cloud 项目中的错误组。

  • LogsPanel：显示存储在当前 Google Cloud 项目中的项目范围日志条目。您可以配置该微件，以显示存储在 Google Cloud 项目中可通过当前指标范围访问的日志条目。

• 文本和组织微件：

  如需将这些 widget 添加到信息中心，信息中心必须具有 MosaicLayout。

  • CollapsibleGroup：显示一系列 widget。您可以收起群组的视图。

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

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

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

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

例如，下面显示了配置右侧 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"
          }
        }
      }
    ]
  }
}

信息中心过滤条件

在设计信息中心时，您可能会发现多种查看信息中心显示的数据的方法。例如，当信息中心显示虚拟机 (VM) 实例的指标时，您可能希望查看所有虚拟机的指标，并且可能需要查看特定地区的指标。在这种情况下，我们建议您创建一个永久过滤器，并将该过滤器的默认值设置为最常用的视图。永久性过滤条件可应用于部分或所有信息中心微件。使用 Google Cloud 控制台查看信息中心时，信息中心工具栏会显示永久性过滤条件以及可用于临时更改过滤条件值的菜单。

信息中心永久性过滤条件有多种类型：

• 信息中心范围的过滤条件适用于信息中心上支持过滤条件标签且未指定该标签值的所有微件。

  例如，如果图表包含过滤条件 zone = us-central1-a，则该图表会忽略基于标签 zone 的信息中心过滤条件。同样，不带 zone 标签的图表会忽略带有此标签的信息中心过滤条件。

• 模板变量是适用于特定 widget 的命名变量。每个变量都对应一个特定的标签和值。您可以决定模板变量应用于哪些 widget。

所有过滤器类型都用相同的数据结构表示。 如需了解详情，请参阅 DashboardFilter。

例如，下面显示了信息中心的部分 JSON 表示法，该信息中心定义了模板变量和信息中心范围的过滤条件：

{
  "dashboardFilters": [
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "instance_id",
        "stringValue": "3133577226154888113",
        "templateVariable": "iid"
      },
      {
        "filterType": "RESOURCE_LABEL",
        "labelKey": "zone"
      }
    ],
  "displayName": "Illustrate Template Variables",
  ...

在显示的 JSON 中，dashboardFilters 结构中的第一个条目是名为 iid 的模板变量和一个标签键为 zone 的信息中心级过滤条件。模板变量是标签 instance_id 的别名。

模板变量的数据结构不会列出它适用的 widget。相反，您可以通过修改 widget 的查询来添加对变量的引用，将 widget 与模板变量相关联。当微件显示在信息中心内时，系统会解析模板变量的值。

如需了解如何为日志面板和图表添加注释，请参阅以下部分：

• “日志”面板
• MQL 定义的图表和表格
• 由 PromQL 定义的图表和表格
• 使用时间序列过滤条件定义的图表和表格

日志面板

如需将日志面板配置为根据模板变量的值过滤显示内容，请将该变量添加到查询窗格。以下示例展示了一个按模板变量 iid 的值进行过滤的查询：

${iid}

在日志面板查询要显示的日志之前，系统会解析模板变量。在此示例中，如果模板变量的值为 "12345"，则 ${iid} 会被替换为语句 resource.labels."instance_id"="12345"。

您还可以在查询中只添加模板变量的值。 我们建议您仅在使用正则表达式定义的过滤条件中使用该值。例如，以下查询使用正则表达式来匹配具有包含所述字符串的 JSON 载荷的日志条目：

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

如果您为日志面板配置了查询，然后选择相应按钮以打开日志浏览器，则模板变量会在打开日志浏览器之前进行解析。

下表显示了日志面板如何解析模板变量：

语法	已选择 值	已解决的日志面板表达式
${iid}	12345	resource.labels."instance_id"="12345"
${iid}	*	""
${iid.value}	12345	12345
${iid.value}	*	.*

由 MQL 定义的图表和表格

使用 Monitoring Query Language (MQL) 配置图表时，请将竖线和变量附加到查询字符串：

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

在图表查询要显示的时序之前，系统会解析模板变量。在此示例中，如果模板变量的值为 "12345"，则 ${iid} 会被替换为语句 filter (resource.instance_id == '12345')。此过滤条件仅匹配带有名为 resource.instance_id 标签的时间序列，并且仅当该标签的值正好为 12345 时。

如果您想使用正则表达式过滤时序，请将查询配置为仅包含模板变量的值。为了说明语法，以下代码展示了如何使用正则表达式确定标签 resource.instance_id 的值是否包含模板变量 iid 的值：

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

下表展示了如何针对 MQL 查询解析模板变量：

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

由 PromQL 定义的图表和表格

使用 PromQL 定义图表时，请将用大括号括起来的变量附加到查询字符串：

compute_googleapis_com:instance_cpu_utilization {
    project_id="my-project", ${iid}
}

在图表查询要显示的时序之前，系统会解析模板变量。在此示例中，如果模板变量的值为 "12345"，则 ${iid} 会被替换为语句 instance_id == '12345'。

与 MQL 类似，当您使用 PromQL 定义 widget 时，查询只能提取模板变量的值。我们建议您仅在通过正则表达式定义的过滤条件中使用该值。为说明语法，以下代码展示了如何使用正则表达式确定标签 instance_id 的值是否包含模板变量 iid 的值：

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

下表展示了如何针对 PromQL 查询解析模板变量：

语法	已选择 值	解析的 PromQL 表达式
${iid}	12345	instance_id == '12345'
${iid}	*	noop_filter=~".*"
${iid.value}	12345	12345
${iid.value}	*	.+

使用时序过滤条件定义的图表和表格

使用时间序列过滤条件定义图表时，请将变量附加到过滤条件字符串：

"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\"
           resource.type=\"gce_instance\" ${iid}"

与 MQL 和 PromQL 定义的图表不同，您不能在时间序列过滤条件中使用模板变量的值。

下表显示了模板变量的解析方式：

语法	已选择 值	解析的过滤器表达式
${iid}	12345	resource.instance_id == "12345"
${iid}	*	已忽略
${iid.value}	12345	不支持
${iid.value}	*	不支持

创建信息中心

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

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

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

协议

如需创建新的信息中心，请向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 参考文档。

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

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

删除信息中心

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

协议

如需删除自定义信息中心，请向 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 参考文档。

列出信息中心

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

协议

要列出项目的所有自定义信息中心，请将项目 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 参考文档。

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

对列表响应进行分页

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

协议

对于结果列表的初始页面，请使用请求指定 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

获取信息中心

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

协议

如需获取特定的自定义信息中心，请将信息中心 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 参考文档。

更新信息中心

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

协议

要更新自定义信息中心，请将 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}

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 值。

后续步骤

• 信息中心和布局示例
• 使用 Google Cloud 控制台创建和管理自定义信息中心