Management Tools

Introducing the Stackdriver Cloud Monitoring dashboards API

Google-Management-tools.jpg

Using dashboards in Stackdriver Cloud Monitoring makes it easy to track critical metrics across time. Dashboards can, for example, provide visualizations to help debug high latency in your application or track key metrics for your applications. Creating dashboards by hand in the Monitoring UI can be a time-consuming process, which may require many iterations. Once dashboards are created, you can save time by using them in multiple Workspaces within your organization. 

Today, we’re pleased to announce that the Stackdriver Cloud Monitoring dashboards API is generally available from Google Cloud. The dashboards API lets you read the configuration for existing dashboards, create new dashboards, update existing dashboards and delete dashboards that you no longer use. These methods follow the REST and gRPC semantics and are consistent with other Google Cloud APIs. 

A common use case for the dashboards API is to deploy a dashboard developed in one Monitoring Workspace into one or more additional Workspaces. For example, you may have a separate Workspace for your development, QA and production environments (learn more on selecting Workspace structures). In one of the environments, you may have developed a standard operational dashboard that you’d like to use across all your Workspaces. By first reading the dashboard configuration via the projects.dashboards.get method, you can save the dashboard configuration and then use the projects.dashboards.create method to create the same dashboard across the other environments.

How the dashboard API works 

When creating a dashboard, you have to specify the layout and the widgets that go inside that layout. A dashboard must use one of three layout types: GridLayout, RowLayout or ColumnLayout. 

  • GridLayout divides the available space into vertical columns of equal width and arranges a set of widgets using a row-first strategy.

  • RowLayout divides the available space into rows and arranges a set of widgets horizontally in each row.

  • ColumnLayout divides the available space into vertical columns and arranges a set of widgets vertically in each column.

The widgets available to place inside the layouts include an XyChart, Scorecard and Text object.

  • XyChart: displays data using X and Y axes. Charts created through the Google Cloud Console are instances of this widget.

  • Scorecard: displays the latest value of a metric, and how this value relates to one or more thresholds. 

  • Text: displays textual content, either as raw text or a markdown string. 

Here’s an example of the JSON dashboard configuration, which specifies a GridLayout with a single XyChart widget. You can see other examples in our sample dashboards and layouts documentation.
  {
  "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"
          }
        }
      }
    ]
  }
}

Dashboard configuration as a template

A simple approach to building a dashboard configuration is to first create a dashboard in the Stackdriver Cloud Monitoring console, then use the dashboards API projects.dashboards.get method to export the JSON configuration. Then, you can share that configuration as a template either via source control or however you normally share files with your colleagues.

You can try out the dashboard API in the Try this API section of the API documentation, and learn more about managing dashboards by reading the Managing Dashboards documentation. We’re working on features to make the API even more useful, including through the gcloud command line. Also, contributors are discussing and planning the Terraform module for the Monitoring Dashboard API in github.


A special thanks to our colleagues David Batelu, Technical Lead and Joy Wang, Product Manager, Stackdriver Cloud Monitoring, for their contributions to this post.