本文档介绍如何使用 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 项目中的项目范围日志条目。您可以配置该 widget,使其显示可通过当前指标范围访问的 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"
}
}
}
]
}
}
信息中心标签
标签可帮助您管理和整理信息中心。例如,您可以添加名为 prod
的标签,以指示信息中心显示生产资源的时间序列数据和日志数据。或者,您也可以添加标签 playbook
,以表明信息中心包含可帮助您排查故障的信息。
向信息中心添加标签是可选操作。
例如,以下代码展示了一个 Dashboard
对象,用于指定名为 playbook
的标签。
{
"displayName": "Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
...
]
},
"dashboardFilters": [],
"labels": {
"playbook": ""
}
}
如上例所示,labels
字段作为 map
实现,其中 key
和 value
字段都是字符串。向信息中心添加标签时,请将 key
设置为标签的名称,并将 value
字段设置为空字符串。
信息中心过滤条件
在设计信息中心时,您可能会以多种方式查看信息中心显示的数据。例如,当信息中心显示虚拟机 (VM) 实例的指标时,您可能希望查看所有虚拟机的指标以及特定地区的指标。在此类情况下,我们建议您创建一个永久过滤器,并将该过滤器的默认值设置为最常用的视图。永久过滤条件可以应用于部分或所有信息中心微件。使用 Google Cloud 控制台查看信息中心时,信息中心工具栏会显示您的永久过滤条件和一个可用于临时更改过滤条件值的菜单。
信息中心的永久过滤条件有多种类型:
信息中心范围的过滤条件会应用于信息中心内支持过滤条件标签且未指定该标签值的所有 widget。
例如,如果图表包含过滤条件
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 与模板变量相关联。当该 widget 在信息中心上显示时,系统会解析模板变量的值。
如需了解如何为日志面板和图表添加注释,请参阅以下部分:
日志面板
如需将日志面板配置为根据模板变量的值过滤显示内容,请将该变量添加到查询窗格。以下示例展示了按模板变量 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 定义微件时,查询只能提取模板变量的值。我们建议您仅在通过正则表达式定义的过滤条件中使用该值。下文说明了如何使用正则表达式来确定标签 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
例如,如果您想复制信息中心,请执行以下操作:
- 完成获取信息中心中的步骤,下载原始信息中心的定义。
- 修改返回的 JSON 以移除
etag
和name
字段,并更改displayName
字段的值。 - 运行该命令以创建信息中心。
如需了解详情,请参阅 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
值。