Example dashboards and layouts

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:

Example dashboard with a grid layout.

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:

Example dashboard with a mosaic layout.

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:

Example dashboard with a row layout.

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:

Example dashboard with column layout

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:

Example of an XyChart.

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:

Example XyChart that uses the left Y-axis and has a threshold.

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:

Example XyChart with a stacked area plot.

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:

Example XyChart with a stacked bar plot.

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:

Example dashboard with a Scorecard widget.

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:

Example dashboard with a Scorecard widget with GaugeView.

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:

Example dashboard with a Scorecard widget with SparkChartView.

Dashboard with a TimeSeriesTable widget

This example shows a dashboard with a TimeSeriesTable widget.

{
  "category": "CUSTOM",
  "displayName": "Pams Table - Sep 7, 2021 1:35 PM",
  "mosaicLayout": {
    "columns": 12,
    "tiles": [
      {
        "height": 5,
        "widget": {
          "timeSeriesTable": {
            "dataSets": [
              {
                "minAlignmentPeriod": "0s",
                "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\""
                  }
                }
              }
            ]
          },
          "title": "VM Instance - CPU utilization [MEAN]"
        },
        "width": 7,
        "xPos": 0,
        "yPos": 0
      }
    ]
  }
}

As shown in the following screenshot, the table widget displays a title, contains a filter bar, and displays data in a tabular format:

Example dashboard with a table widget.

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:

Example dashboard with a text widget.

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:

Example of an alert chart.

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 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:

Example dashboard with a blank widget.