Managing dashboards by API

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

• dashboards.create: creates a new dashboard
• dashboards.delete: deletes a specified dashboard
• dashboards.list: retrieves a list of all dashboards in a given project
• dashboards.get: retrieves a specified dashboard
• dashboards.patch: updates the structure of a specified dashboard

You can invoke the API directly by using the curl utility or by using the gcloud command-line tool.

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.

Note: You can't retrieve, edit, or delete predefined dashboards by using the 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 the following layouts:

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

• MosaicLayout: divides the available space into a grid. Each widget can occupy one or more grid blocks.

• 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

Any widget that displays data retrieved from a time series will have a TimeSeriesQuery object embedded in it. This object specifies the time-series data to be used in the widget.

You can specify the time-series data to display as follows:

• By using Monitoring filters. Filters are used in TimeSeriesFilter and TimeSeriesFilterRatio queries. For more information on retrieving metric data this way, see Reading metric data.

• By using Monitoring Query Language (MQL). This approach uses an MQL query in a TimeSeriesQuery object. The query string is passed as the value of the timeSeriesQueryLanguage field.

  • For general information on MQL, see Using Monitoring Query Language.
  • For information on supplying MQL queries for charts, see Using MQL from the Monitoring API: Charts.

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.

Examples using curl

This section describes the conventions and setup used for invoking the Dashboard API by using the curl tool. The examples on this page access the API by using the curl tool to send HTTP requests to REST endpoints. Use the following information on authentication and invoking curl to set the variables used in the example invocations.

Authentication

1. Create an environment variable to hold the ID of your Cloud Monitoring Workspace. These examples use PROJECT_ID:

   PROJECT_ID=a-gcp-project-12345
   

2. Authenticate to Cloud SDK:

   gcloud auth login
   

3. Optionally, you can avoid having to specify your project ID with each command by setting it as the default by using Cloud SDK:

   gcloud config set project ${PROJECT_ID}
   

4. Create an authorization token and capture it in an environment variable. These examples call the variable ACCESS_TOKEN:

   ACCESS_TOKEN=`gcloud auth print-access-token`
   

   You have to periodically refresh the access token. If commands that worked suddenly report that you're unauthenticated, re-issue this command.

5. To verify that you got an access token, echo the ACCESS_TOKEN variable:

   echo ${ACCESS_TOKEN}
   ya29.ImW8Bz56I04cN4qj6LF....
   

Invoking curl

Each curl invocation includes a set of arguments, followed by the URL of a Dashboard API resource. The common arguments include values specified by the PROJECT_ID and ACCESS_TOKEN environment variables. You might also have to specify other arguments, for example, to specify the type of the HTTP request (for instance, -X DELETE).

Each curl invocation has this general structure:

curl -H "Authorization: Bearer $ACCESS_TOKEN" <other_args> https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/<request>

For example, to list all the dashboards in your project, issue the following request:

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

This request returns a list of dashboards associated with your project:

{
  "dashboards": [
    {
      "name": "projects/123456789000/dashboards/c2ab1f1c-b8b9-1234-9c48-c7745802b659",
      "displayName": "Grid-layout example",
      "etag": "76a95cc500a7c7d6b3799709c13afe91",
      "gridLayout": {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    },
    {
      "name": "projects/123456789000/dashboards/cae85db7-6920-4e67-a45c-97a94c0e2679",
      "displayName": "Row-layout example",
      "etag": "a600be01afe0b37762cd7a9b92fc3e7e",
      "rowLayout": {
        "rows": [
          {
            "widgets": [
              {
                "text": {
                  "content": "Text Widget 1",
                  "format": "RAW"
                }
              },
              {
                "text": {
                  "content": "**Text Widget 2**",
                  "format": "MARKDOWN"
                }
              },
              {
                "text": {
                  "content": "_Text Widget 3_",
                  "format": "MARKDOWN"
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

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.

curl -d @my-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X POST https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

To create a dashboard in a project, use the gcloud monitoring dashboards create command.

gcloud monitoring dashboards create --config-from-file=my-dashboard.json

For more information, see the gcloud monitoring dashboards create reference.

The examples create a sample dashboard by using the my-dashboard.json file. You can now manage your dashboard through the Google Cloud Console.

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

Deleting dashboards

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

Protocol

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

curl -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/[DASHBOARD_ID]

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

gcloud

To delete a custom dashboard, use gcloud monitoring dashboards delete, and specify the fully qualified ID of the dashboard to delete:

gcloud monitoring dashboards delete projects/[MY_PROJECT_ID]/dashboards/[MY_DASHBOARD_ID]

For more information, see the gcloud monitoring dashboards delete reference.

Listing dashboards

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

Protocol

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

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards

gcloud

To list all of a project's custom dashboards, use the gcloud monitoring dashboards list command:

gcloud monitoring dashboards list

For more information, see the gcloud monitoring dashboards list reference.

The examples return the dashboards associated with your project.

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 -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards?page_size=1

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.

gcloud

To specify the number of resources per page, pass the --page-size flag with the command. For example:

gcloud monitoring dashboards list --page-size=1

Getting dashboards

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

Protocol

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

curl -H "Authorization: Bearer $ACCESS_TOKEN" https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/[DASHBOARD_ID]

The method returns a response similar to the following example:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

gcloud

To get a specific custom dashboard, use the gcloud monitoring dashboards describe command and specify the dashboard ID:

gcloud monitoring dashboards describe [DASHBOARD_ID] --format=json

The command returns the requested dashboard:

{
  "columnLayout": {
    "columns": [
      {
        "widgets": [
          {
            "text": {
              "content": "Text Widget 1",
              "format": "RAW"
            }
          },
          {
            "text": {
              "content": "**Text Widget 2**",
              "format": "MARKDOWN"
            }
          },
          {
            "text": {
              "content": "_Text Widget 3_",
              "format": "MARKDOWN"
            }
          }
        ]
      }
    ]
  },
  "displayName": "Column-layout example",
  "etag": "cb3070baf15de7c79d78761baac3a386",
  "name": "projects/730041941835/dashboards/e4cd063e-5414-4e07-9e1e-450d6d3a531d"
}

For more information, see the gcloud monitoring dashboards describe reference.

Updating dashboards

To update an existing custom 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 custom 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 -d @my-updated-dashboard.json -H "Authorization: Bearer $ACCESS_TOKEN" -H 'Content-Type: application/json' -X PATCH https://monitoring.googleapis.com/v1/projects/${PROJECT_ID}/dashboards/[DASHBOARD_ID]

gcloud

To update a custom dashboard, use gcloud monitoring dashboards update, specify the ID of the dashboard to update, and provide the changes to the dashboard.

gcloud monitoring dashboards update [DASHBOARD_ID] --config-from-file=my-updated-dashboard.json

For more information, see the gcloud monitoring dashboards update reference.

The examples update an existing dashboard using the my-updated-dashboard.json file and return a copy of the updated dashboard listing, including a new etag value.