This guide illustrates additional dashboard configurations you can create by using the Cloud Monitoring API. For additional examples, see Installable dashboards.
When to use the API
The Cloud Monitoring API provides you with a way of managing many dashboards at once. While you can use the Google Cloud Console to manage your dashboards, you may find it easier to use the API to manage your custom dashboards in bulk.
You also need to use the API if you want to add the Text,
Scorecard, or blank placeholder widgets to your
dashboard.
Using MQL with the API
When you create a dashboard, you can provide a MQL query
to the TimeSeriesQuery
specification in the dashboards.create method.
For more information, see Building charts.
Dashboard layouts
Dashboard in GridLayout
This dashboard shows a GridLayout with three widgets.
{
"displayName": "Grid Layout Example",
"gridLayout": {
"columns": "2",
"widgets": [
{
"title": "Widget 1",
"xyChart": {
"dataSets": {
"timeSeriesQuery": {
"timeSeriesFilter": {
"filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
"aggregation": {
"perSeriesAligner": "ALIGN_RATE"
}
},
"unitOverride": "1"
},
"plotType": "LINE"
},
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
{
"text": {
"content": "Widget 2"
}
},
{
"title": "Widget 3",
"xyChart": {
"dataSets": {
"timeSeriesQuery": {
"timeSeriesFilter": {
"filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
"aggregation": {
"perSeriesAligner": "ALIGN_RATE"
}
},
"unitOverride": "1"
},
"plotType": "STACKED_BAR"
},
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
}
]
}
}
The dashboard looks similar to the following example:
Dashboard in MosaicLayout
This dashboard shows a MosaicLayout with two widgets.
{
"displayName": "Mosaic Layout Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"xPos": 2,
"yPos": 2,
"width": 7,
"height": 2,
"widget": {
"title": "CPU utilization in us-central1-a",
"scorecard": {
"timeSeriesQuery": {
"timeSeriesFilter": {
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" resource.label.zone=\"us-central1-a\"",
"aggregation": {
"perSeriesAligner": "ALIGN_MEAN",
"crossSeriesReducer": "REDUCE_MAX"
}
},
"unitOverride": "1"
},
"gaugeView": {
"upperBound": 1.5
},
"thresholds": [
{
"value": 0.8,
"color": "YELLOW",
"direction": "ABOVE"
},
{
"value": 1,
"color": "RED",
"direction": "ABOVE"
}
]
}
}
},
{
"xPos": 1,
"yPos": 5,
"width": 4,
"height": 4,
"widget": {
"title": "My 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",
"minAlignmentPeriod": "60s"
}
],
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
}
}
]
}
}
The dashboard looks similar to the following example:
Dashboard in RowLayout
This dashboard displays a RowLayout with three widgets.
{
"displayName": "Row Layout Example",
"rowLayout": {
"rows": [
{
"weight": "1",
"widgets": [
{
"text": {
"content": "Widget 1",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "Widget 2",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "Widget 3",
"format": "MARKDOWN"
}
}
]
}
]
}
}
The dashboard looks similar to the following example:
Dashboard in ColumnLayout
This dashboard displays a ColumnLayout with three
widgets.
{
"displayName": "Column Layout Example",
"columnLayout": {
"columns": [
{
"weight": "1",
"widgets": [
{
"text": {
"content": "Widget 1",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "Widget 2",
"format": "MARKDOWN"
}
},
{
"text": {
"content": "Widget 3",
"format": "MARKDOWN"
}
}
]
}
]
}
}
The dashboard looks similar to the following example:
Dashboards with Widgets
Dashboard with an XyChart
This dashboard shows a dashboard with a basic XyChart. If
you ever used the Google Cloud Console to create charts on dashboards, those charts
are instances of the XyChart widget.
Similar to the functionality provided in the Cloud Console, the API
provides options to change the chart's PlotType or to
configure the chart's view modes.
{
"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"
}
}
}
]
}
}
The dashboard looks similar to the following example:
Dashboard with an XyChart with a STACKED_AREA PlotType
This dashboard shows an XyChart with a STACKED_AREA
PlotType.
{
"displayName": "Demo dashboard",
"gridLayout": {
"widgets": [
{
"title": "Sample stacked-area 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": "STACKED_AREA"
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
},
"chartOptions": {
"mode": "COLOR"
}
}
}
]
}
}
The dashboard looks similar to the following example:
Dashboard with an XyChart with a STACKED_BAR PlotType
This dashboard shows an XyChart with a STACKED_BAR
PlotType.
{
"displayName": "Demo Dashboard",
"gridLayout": {
"widgets": [
{
"title": "My First 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": "STACKED_BAR"
}
],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
},
"chartOptions": {
"mode": "COLOR"
}
}
},
]
}
}
The dashboard looks similar to the following example:
Dashboard with a basic Scorecard
This dashboard shows a Scorecard without a gauge or
sparkline. It shows the Compute Engine CPU utilization, and has two thresholds,
one that uses the color yellow to indicate that CPU utilization is over 70%,
and one that uses red to indicate that the CPU utilization is over 90%.
Because the current CPU utilization falls below the specified thresholds, it is considered a pass.
{
"displayName": "Unadorned scorecard",
"gridLayout": {
"widgets": [
{
"title": "Compute Engine CPU utilization",
"scorecard": {
"timeSeriesQuery": {
"timeSeriesFilter": {
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"aggregation": {
"perSeriesAligner": "ALIGN_MEAN",
"crossSeriesReducer": "REDUCE_MAX",
}
},
"unitOverride": "1"
},
"thresholds": [
{
"color": "RED",
"direction": "ABOVE",
"label": "Danger",
"value": 0.9,
},
{
"color": "YELLOW",
"direction": "ABOVE",
"label": "Warning",
"value": 0.7,
}
]
}
},
]
}
}
The dashboard looks similar to the following example:
Dashboard with a Scorecard with GaugeView
This dashboard adds a gauge to the basic scorecard in the previous example.
The GaugeView object can specify an upper and a lower bound, to specify the
range of values to show on the gauge. Since the scorecard shows values from
0 to 1, those are reasonable upper and lower bounds. To add the gauge, add the
following to the JSON for the basic scorecard:
"gaugeView": {
"lowerBound": 0,
"upperBound": 1,
},
The following shows the complete modified dashboard specification: The current value is under the thresholds, which are colored appropriately on the gauge.
{
"displayName": "Gauge scorecard",
"gridLayout": {
"widgets": [
{
"title": "Compute Engine CPU utilization",
"scorecard": {
"timeSeriesQuery": {
"timeSeriesFilter": {
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"aggregation": {
"perSeriesAligner": "ALIGN_MEAN",
"crossSeriesReducer": "REDUCE_MAX",
}
},
"unitOverride": "1"
},
"gaugeView": {
"lowerBound": 0,
"upperBound": 1,
},
"thresholds": [
{
"color": "RED",
"direction": "ABOVE",
"label": "Danger",
"value": 0.9,
},
{
"color": "YELLOW",
"direction": "ABOVE",
"label": "Warning",
"value": 0.7,
}
]
}
},
]
}
}
The dashboard looks similar to the following example:
Dashboard with a Scorecard with SparkChartView
This dashboard replaces the gauge in the previous example with a sparkline.
The SparkChartView object can create line charts or bar charts on a scorecard.
This example uses a line. As long as the value doesn't violate a threshold, it
is green. To add the sparkline, replace the gaugeView JSON object in the
previous chart with the following:
"sparkChartView": {
"sparkChartType": "SPARK_LINE"
},
The dashboard looks similar to the following example:
Dashboard with a Text widget
This example shows a simple dashboard with a Text widget.
{
"displayName": "Demo Dashboard"
"gridLayout": {
"widgets": [
{
"text" {
"content": "Hello World"
}
}
]
}
}
The dashboard looks similar to the following example:
Dashboard with a blank widget
This example shows a simple dashboard with an empty, placeholder widget. Note
that only the dashboard's displayName appears in the widget.
{
"displayName": "Demo Dashboard",
"gridLayout": {
"widgets": [
{
"blank": {}
}
]
}
}
The dashboard looks similar to the following example:
