This page illustrates how you can create dashboards by using the Cloud Monitoring API. For each example, the dashboard definition in JSON and the corresponding dashboard are shown.
Cloud Monitoring also provides a curated set of dashboard definitions on GitHub. You can install these definitions in your Google Cloud project as custom dashboards. For information about this repository and how to install these dashboards, see Install sample 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 when you want to add the blank placeholder widget to your dashboard.
Using MQL with the API
When you create a dashboard, you can provide an 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 Google 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:
The next section illustrates how to display a threshold on a chart, and how to configure whether the chart uses the left Y-axis, right Y-axis, or both.
Dashboard with an XyChart and a threshold
This dashboard shows a dashboard with a basic XyChart,
a threshold, and the left Y-axis configured.
{
"category": "CUSTOM",
"displayName": "Dashboard with xyChart",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"title": "VM Instance - CPU utilization [MEAN]",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"minAlignmentPeriod": "60s",
"plotType": "LINE",
"targetAxis": "Y2",
"timeSeriesQuery": {
"apiSource": "DEFAULT_CLOUD",
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"secondaryAggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_NONE"
}
}
}
}
],
"thresholds": [
{
"label": "",
"targetAxis": "Y2",
"value": 0.45
}
],
"timeshiftDuration": "0s",
"y2Axis": {
"label": "y2Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 0,
"yPos": 0
}
]
}
}
In the preceding example, the JSON specifies the use of the left Y-axis because
it contains a y2Axis structure. In the targetAxis field, use "Y1" for the
right Y-axis and "Y2" for the left Y-axis. If you omit the targetAxis
field, then the right Y-axis is used.
The chart on this dashboard looks similar to the following example:
You can construct charts that display multiple metric types and that use
the left and right axes. The previous example illustrated a chart with
a single metric type, that is, there is one element in the dataSets array.
When you chart two metric types, the dataSets array contains two elements,
and each element specifies its targetAxis.
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. The example shows the Compute Engine CPU utilization and the scorecard
has two thresholds. One threshold uses the color yellow to indicate that
CPU utilization is over 70%, the other threshold uses red to indicate that the
CPU utilization is over 90%.
Because the current CPU utilization is less than the specified thresholds, the color is green.
{
"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 upper and lower bounds are reasonable. 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 TimeSeriesTable widget
Dashboards can display data in a tabular format, where there is one row for each monitored time series. Tables don't show data over time; instead, they show only the most recent value.
All tables are specified by the TimeSeriesTable widget:
To configure the maximum number of rows to display, set the
pickTimeSeriesFilterfield. For example, to display only the two time series with the largest average value over the previous 10 minutes, include the following:"pickTimeSeriesFilter": { "direction": "TOP", "numTimeSeries": 2, "rankingMethod": "METHOD_MEAN" },If you omit the
pickTimeSeriesFilterfield, then the table displays a maximum of 300 rows.To configure how the table displays the data, use the
metricVisualizationfield:- To display only a value like "25%", either omit this field or set the
value to
"NUMBER". When you use this configuration, the Google Cloud console displays the widget as a Table widget. - To display the value and a visual indicator of the value compared to the
range of possible values, set the value of this field to
"BAR". When you use this configuration, the Google Cloud console displays the widget as a Top List widget.
- To display only a value like "25%", either omit this field or set the
value to
To configure which columns are displayed, use the
columnSettingsfield. The following example results in a table with two columns, one titledLatest Value, which is a mandatory column, and the other titledName (from instance_id):"columnSettings": [ { "column": "Name (from instance_id)", "visible": true }If you omit the
columnSettingsfield, then the table displays one column for each label.
The following example shows a dashboard with a Table widget and a Top List widget:
{
"category": "CUSTOM",
"dashboardFilters": [],
"displayName": "Top List and Table example",
"labels": {},
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"timeSeriesTable": {
"dataSets": [
{
"minAlignmentPeriod": "60s",
"tableDisplayOptions": {},
"timeSeriesQuery": {
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"secondaryAggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_NONE"
}
}
}
}
],
"metricVisualization": "NUMBER"
},
"title": "VM Instance - CPU utilization [MEAN]"
},
"width": 6,
"xPos": 0,
"yPos": 4
},
{
"height": 4,
"widget": {
"timeSeriesTable": {
"columnSettings": [
{
"column": "Name (from instance_id)",
"visible": true
}
],
"dataSets": [
{
"minAlignmentPeriod": "60s",
"tableDisplayOptions": {},
"timeSeriesQuery": {
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"pickTimeSeriesFilter": {
"direction": "TOP",
"numTimeSeries": 300,
"rankingMethod": "METHOD_MEAN"
},
"secondaryAggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_NONE"
}
}
}
}
],
"metricVisualization": "BAR"
},
"title": "VM Instance - CPU utilization [MEAN]"
},
"width": 6,
"xPos": 0,
"yPos": 0
}
]
}
}
As shown in the following screenshot, both widgets display data in a tabular form, and they both contain a filter bar. However, the two widgets are preconfigured to show different columns and to represent the numeric value differently:
The columns of the table correspond to labels. Each row corresponds to a time series.
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 an AlertChart widget
This dashboard shows a dashboard with an AlertChart
widget:
{
"category": "CUSTOM",
"displayName": "Alert chart example",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 8,
"widget": {
"alertChart": {
"name": "projects/my-project/alertPolicies/14205854094151528373"
}
},
"width": 9,
"xPos": 0,
"yPos": 0
}
]
}
}
Unlike other dashboard widgets, you don't specify a title or a metric filter
for these widgets. Instead, you specify the resource name for an alerting
policy. The last entry in the name field is the alerting policy identifier.
The dashboard looks similar to the following example:
In this example, the alerting policy is monitoring the CPU usage of two
different virtual machines. The dashed line shows the condition threshold,
which is set to 50%. The green chip with the label No incidents
indicates that there are no open incidents for the alerting policy. If
you place your pointer on the incidents chip, then a dialog opens that
links to the underlying alerting policy.
Dashboard with an IncidentList widget
This dashboard shows a dashboard with an IncidentList
widget:
{
"category": "CUSTOM",
"dashboardFilters": [],
"displayName": "Incident widget",
"labels": {},
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 5,
"widget": {
"incidentList": {
"monitoredResources": [
{
"labels": {},
"type": "gce_instance"
}
],
"policyNames": []
},
"title": "Incidents"
},
"width": 8,
"xPos": 0,
"yPos": 0
}
]
}
}
}
The previous example sets the title field to Incidents, and it configures
the widget to display all incidents for resources of type gce_instance.
When you configure this widget, you can select multiple alerting policies or
multiple resource types.
The dashboard looks similar to the following example:
Dashboard with a LogsPanel widget
This dashboard shows a dashboard with a LogsPanel
widget:
{
"category": "CUSTOM",
"displayName": "Demo Logs Panel",
"labels": {
"pams": ""
},
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"logsPanel": {
"filter": "",
"resourceNames": [
"projects/012012012012"
]
},
"title": "Logs Panel"
},
"width": 6,
"xPos": 0,
"yPos": 0
}
]
}
}
We recommend that you configure the height of a logs panel to be at least 3 units, and its width to be at least 4 units. In the previous example, the widget has a height of 4 units and width of 6 units.
The logs panel displays the logs from the Google Cloud projects listed
in the resourceNames field. The previous example specifies only one project;
however, you can include multiple projects in this list.
The logs panel looks similar to the following example:
For troubleshooting information, see API call to create dashboard with a logs panel fails.
Dashboard with a CollapsibleGroup widget
This dashboard shows a dashboard with a CollapsibleGroup
widget:
{
"category": "CUSTOM",
"displayName": "Group testing",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 4,
"widget": {
"collapsibleGroup": {
"collapsed": false
},
"title": "My group"
},
"width": 12,
"xPos": 0,
"yPos": 0
},
{
"height": 4,
"widget": {
"title": "VM Instance - CPU utilization [MEAN]",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"minAlignmentPeriod": "60s",
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"apiSource": "DEFAULT_CLOUD",
"timeSeriesFilter": {
"aggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_MEAN"
},
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\"",
"secondaryAggregation": {
"alignmentPeriod": "60s",
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_NONE"
}
}
}
}
],
"thresholds": [],
"timeshiftDuration": "0s",
"yAxis": {
"label": "y1Axis",
"scale": "LINEAR"
}
}
},
"width": 6,
"xPos": 0,
"yPos": 0
}
]
}
}
In the previous example, the collapsible group widget contains a single chart
that displays the CPU utilization of a VM instance. Collapsible group widgets
span an entire row of a table. A widget is included in a group when the
group's (x,y) position and height specifications include the (x,y)
position of the widget. In the previous example, the group is at the position
of (0,0) and its height is 4. The xyChart is at the position of (0,0), so
it is included in the group. However, if the position of that chart is
changed to be (0,5), then the chart is excluded from the group. Lastly, when
a widget's (x,y) position result in the widget being included in the group, the
height of the collapsible group widget might be expanded.
To include a group widget on a dashboard, the dashboard must have a
MosaicLayout.
The collapsible group widget looks similar to the following example:
Dashboard with an SLO widget
This dashboard shows a dashboard with a SLO widget:
{
"category": "CUSTOM",
"displayName": "SLO widget on dashboard",
"mosaicLayout": {
"columns": 12,
"tiles": [
{
"height": 6,
"widget": {
"title": "SLO Error Budget: 95% - Metric Mean in Range - Calendar week",
"xyChart": {
"chartOptions": {
"mode": "COLOR"
},
"dataSets": [
{
"legendTemplate": "Remaining error requests before SLO is burned",
"plotType": "LINE",
"targetAxis": "Y1",
"timeSeriesQuery": {
"apiSource": "DEFAULT_CLOUD",
"timeSeriesFilter": {
"aggregation": {
"crossSeriesReducer": "REDUCE_NONE",
"perSeriesAligner": "ALIGN_NEXT_OLDER"
},
"filter": "select_slo_budget(\"projects/Project_Number/services/SERVICE_ID/serviceLevelObjectives/SLO_ID\")",
"secondaryAggregation": {
"crossSeriesReducer": "REDUCE_NONE"
}
},
"unitOverride": "1"
}
}
],
"thresholds": []
}
},
"width": 10,
"xPos": 0,
"yPos": 0
}
]
}
}
As the previous JSON shows, SLO charts are represented as
XyChart objects. These objects specify all
aggregation fields, thresholds, and the
value of the filter field is a time-series selector. For more information
about these selectors, see Retrieving SLO data.
The SLO widget looks similar to the following example:
Dashboard with a blank widget
This example shows a simple dashboard with an empty, placeholder widget.
The value of the displayName field appears in the widget.
{
"displayName": "Demo Dashboard",
"gridLayout": {
"widgets": [
{
"blank": {}
}
]
}
}
The dashboard looks similar to the following example:
Dashboards with permanent filters
For an example of a dashboard with a permanent filter, see Dashboard filters.