Managing dashboards by API

You can manage dashboards and charts by using the Dashboard resource in the Stackdriver Monitoring API. The endpoint supports the following methods for managing and configuring dashboards:

While you can also manage your dashboards through the Google Cloud Console, the API provides you with a programmatic way of managing many dashboards at the same time. Also, since charts are implemented as widgets on dashboards, you can also create, configure, and manipulate charts by using the Dashboard API.

Before you begin

When creating a dashboard, you must specify which components, or widgets, you want to display, and the layout for those widgets.

Defining the dashboard layout

Layouts define how the components of a dashboard are ordered. The API provides three layouts:

  • 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.

For example, the following shows the JSON representation of a dashboard in RowLayout with three Text widgets:

{
  "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"
            }
          }
        ]
      }
    ]
  }
}

Defining widgets

A widget contains a single dashboard component and the configuration of how to present the component in the dashboard. A dashboard can have more than one widget. There are three types of Widget objects:

  • 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. You can only create this widget by using the API.

  • Text: displays textual content, either as raw text or a Markdown string. You can only create this widget by using the API.

In addition to these objects, you can also add a blank placeholder to a dashboard.

For example, the following shows the JSON representation of an XyChart widget:

{
  "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"
          }
        }
      }
    ]
  }
}

Specifying the data to display

If you created charts through Google Cloud Console, then you are already familiar with metrics and time series. In addition to XyChart, you can visualize your data through additional widgets by using the Dashboard API.

For information on metrics and time series, go to Metrics, Time Series, and Resources.

In addition, you may find the Creating charts, Selecting metrics, and Setting view options guides helpful. While these guides are written for creating charts through the Google Cloud Console, the concepts for creating a chart, selecting metrics, and selecting view options also apply to creating charts by using the Dashboard API.

Creating a dashboard

To create a new custom dashboard, invoke the dashboards.create method and provide it with the layout and the widgets to display in the dashboard.

When you create a dashboard, the API automatically generates the dashboard_id. If you want to specify a custom dashboard_id, you can set the name field of a Dashboard object. The format of the name field looks like the following:

"name": "projects/<host_project_id>/dashboards/<dashboard_id>"

In the API, host_project_id must be the host project for a Workspace. If you specify a Google Cloud project identifier that isn't associated with a Workspace, or that isn't a host project for a Workspace, a 400 error occurs. See Workspaces for more information on how to create and manage a Workspace.

Protocol

To create a new dashboard, send a POST request to the Dashboard endpoint, qualified with the dashboard's layout and widgets.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_number>/dashboards' -X POST -H "Content-Type:application/json" -H 'Authorization: Bearer <auth_token>' --data '{
        "displayName": "Untitled Dashboard",
        "gridLayout": {
          "columns": "1",
            "widgets": [
              {
                "title": "Example Scorecard",
                "scorecard": {
                  "timeSeriesQuery": {
                    "timeSeriesFilter": {
                      "filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
                      "aggregation": {
                        "perSeriesAligner": "ALIGN_RATE",
                        "crossSeriesReducer": "REDUCE_SUM"
                      }
                    },
                    "unitOverride": "1"
                  },
                  "gaugeView": {
                    "upperBound": 65
                  },
                  "thresholds": [
                    {
                      "value": 70,
                      "color": "RED",
                      "direction": "BELOW"
                    }
                  ]
                }
              }
            ]
          }' --compressed

The method returns a response similar to the following example:

{
  "name": "projects/<host_project_id>/dashboards/<dashboard_id>",
  "displayName": "Untitled Dashboard",
  "etag": "<etag_value>",
  "gridLayout": {
    "columns": "1",
    "widgets": [
      {
        "title": "Example Scorecard",
        "scorecard": {
          "timeSeriesQuery": {
            "timeSeriesFilter": {
              "filter": "metric.type=\"agent.googleapis.com/nginx/connections/accepted_count\"",
              "aggregation": {
                "perSeriesAligner": "ALIGN_RATE",
                "crossSeriesReducer": "REDUCE_SUM"
              }
            },
            "unitOverride": "1"
          },
          "gaugeView": {
            "upperBound": 65
          },
          "thresholds": [
            {
              "value": 70,
              "color": "RED",
              "direction": "BELOW"
            }
          ]
        }
      }
    ]
  }
}

For additional dashboard configurations, go to Sample dashboards and layouts.

Deleting dashboards

To delete a dashboard, invoke the dashboards.delete method and specify the dashboard you want to delete.

Protocol

To delete a dashboard, send a DELETE request to the Dashboard endpoint, qualified with the ID of the dashboard to delete.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -X DELETE -H 'Authorization: Bearer <auth_token>' --compressed

If successful, the method returns an empty response. Otherwise, it returns an error.

Listing dashboards

To list all the dashboards that belong to a project, invoke the dashboards.list method and specify the project ID.

Protocol

To list all of a project's dashboards, send the project ID to the Dashboard endpoint.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards' -H 'Authorization: Bearer <auth_token>' --compressed

The method returns a response similar to the following example:

"dashboards": [
  {
    "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
    "displayName": "Untitled Dashboard"
    "etag": "<etag_value>"
    "gridLayout" {
      "columns": 2
      "widgets": [
        {
          "title": "Produced API - Request sizes [SUM]"
          "xyChart" {
            "dataSets" {
              "timeSeriesQuery" {
                "timeSeriesFilter" {
                  "filter": "metric.type=\"aws.googleapis.com/DynamoDB/UserErrors/Sum\""
                  "aggregation" {
                    "perSeriesAligner": "ALIGN_RATE"
                  }
                }
                "unitOverride": "1"
              }
              "plotType": "LINE"
              "minAlignmentPeriod" {
                "seconds": 60
              }
            }
            "timeshiftDuration" {
            }
            "yAxis" {
              "label": "y1Axis"
              "scale": "LINEAR"
            }
            "chartOptions" {
              "mode": "COLOR"
            }
          }
        }
      ]
    }
  },
  {
    "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
    "displayName: "Untitled Dashboard"
    "etag": "<etag_value>"
    "gridLayout" {
      "columns": 2
    }
  }
]

Paginating the list response

The dashboards.list method supports pagination, which allows you to take the results one page at a time instead of all at once.

Protocol

For the initial page of the results list, specify the pageSize query parameter with request:

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards?page_size=1' -H 'Authorization: Bearer <auth_token>' --compressed

The method returns the first page of the list and the nextPageToken. For example:

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

For each remaining pages, you must include the corresponding nextPageToken in the request.

Getting dashboards

To get a dashboard for a project, invoke the dashboards.get method, qualified with the dashboard ID.

Protocol

To get a specific dashboard, send the dashboard ID to the Dashboard endpoint.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -H 'Authorization: Bearer <auth_token>' --compressed

The method returns a response similar to the following example:

{
  "name": "projects/<host_project_id>/dashboards/<dashboard_id>"
  "displayName": "Demo Dashboard"
  "etag": "<etag_value>"
  "gridLayout" {
    "widgets": [
      {
        "text" {
          "content": "Hello World"
        }
      }
    ]
  }
}

Updating dashboards

To update an existing dashboard, invoke the dashboards.patch method. To get the current etag value, you can invoke the dashboards.get method and find it in the response.

Protocol

To update a dashboard, send a PATCH request to the Dashboard endpoint and supply the revised Dashboard object and the etag value from the most recent dashboards.get response.

curl 'https://monitoring.googleapis.com/v1/projects/<host_project_id_or_name>/dashboards/<dashboard_id>' -X PATCH -H "Content-Type: application/json" -H "Authorization: Bearer <auth_token>" --data '{
  "name": "projects/<host_project_id_or_name>/dashboards/<dashboard_id>",
  "displayName": "Updated Title",
  "etag": "<etag_value>",
  "gridLayout": {
    "columns": 2,
    "widgets": [
      {
        "blank": {}
      }
    ]
  }
}'

The method returns the updated Dashboard object.

Was this page helpful? Let us know how we did:

Send feedback about...

Stackdriver Monitoring