通过 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 的布局。您还可以 向信息中心添加标签和过滤条件。标签可帮助您查找信息中心 或指明信息中心内内容的类型

信息中心布局

布局定义了信息中心组件的排序方式。该 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：显示突发事件列表。您可以 配置 widget，以显示特定提醒政策或针对 特定资源类型。

• 日志和错误微件：

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

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

• 文本和组织微件：

  要在一个 信息中心，则必须为该信息中心设置 MosaicLayout。

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

  • SingleViewGroup：在 一组微件您可以选择要显示的微件。

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

信息中心标签

标签可帮助您管理和整理信息中心。例如，您 可能会添加一个名为 prod 的标签，以指明信息中心显示的是 时间序列数据和日志数据。或者 则可以添加标签playbook来指示信息中心 包含有助于您排查故障的信息。

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

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

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

如上例所示，labels 字段实现为 map，其中 key 和 value 字段都是字符串。添加 将标签设置为信息中心，将 key 设置为标签的名称，然后将 value 字段为空字符串。

信息中心过滤条件

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

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

• 信息中心范围的过滤条件适用于信息中心上支持 过滤器标签，并且不为该标签指定值。

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

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

所有过滤器类型均以相同的数据结构表示。 如需了解详情，请参阅 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 显示在信息中心内时， 模板变量的值已解析。

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

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

日志面板

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

${iid}

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

您还可以在查询中仅包含模板变量的值。 我们建议您仅在使用 正则表达式。例如，以下查询使用正则表达式 来匹配具有 JSON 载荷，其中包含描述的 字符串：

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

如果您为日志面板配置了查询，请选择相应按钮 打开日志浏览器时，会先解析模板变量， Logs Explorer 打开。

下表展示了系统如何通过 日志面板：

语法	Selected 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 解析模板变量 查询：

语法	Selected Value	解析的 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 定义微件时，查询 只能提取模板变量的值。我们建议您 只将该值用作通过正则表达式定义的过滤器的一部分。接收者 下面对语法进行了说明，下面介绍了如何使用正则表达式 确定标签 instance_id 的值是否包含 模板变量 iid：

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

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

语法	Selected Value	已解析的 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 定义的图表不同，您不能使用该值 时序过滤条件中模板变量的值。

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

语法	Selected Value	已解决的过滤条件表达式
${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 控制台创建和管理自定义信息中心