本文档介绍了如何创建和管理
自定义信息中心和这些信息中心上的微件
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 显示在信息中心内时, 模板变量的值已解析。
如需了解如何为日志面板和图表添加注释,请参阅以下部分:
日志面板
要将日志面板配置为根据
模板变量,请将该变量添加到查询窗格中。以下示例
展示了按模板变量 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
例如,如果您想复制信息中心,请执行以下操作:
- 完成获取信息中心中的步骤,下载 原始信息中心
- 修改返回的 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
值。