This page describes how you can manage custom dashboards and charts by using
the Dashboard
resource in the Cloud Monitoring API.
While you can also manage your custom 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 Cloud Monitoring API.
The endpoint supports the following methods for managing and configuring dashboards:
dashboards.create
: creates a new dashboarddashboards.delete
: deletes a specified dashboarddashboards.list
: retrieves a list of all dashboards in a given projectdashboards.get
: retrieves a specified dashboarddashboards.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.
You can't retrieve, edit, or delete predefined dashboards by using the API.
Before you begin
Configure a Cloud Monitoring Workspace for your project by doing the following:- In the Cloud Console, select your Google Cloud project.
Go to Cloud Console - In the navigation pane, select Monitoring.
If you have never used Cloud Monitoring, then on your first access of Monitoring in the Google Cloud Console, a Workspace is automatically created and your project is associated with that Workspace. Otherwise, if your project isn't associated with a Workspace, then a dialog appears and you can either create a Workspace or add your project to an existing Workspace. We recommend that you create a Workspace. After you make your selection, click Add.
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
andTimeSeriesFilterRatio
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 thetimeSeriesQueryLanguage
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 Cloud Monitoring 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 Cloud Monitoring API.
Examples using curl
This section describes the conventions and setup used for invoking the
Cloud Monitoring 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
Create an environment variable to hold the ID of your Cloud Monitoring scoping project of a metrics scope (or the Workspace's host project). These examples use
HOST_PROJECT_ID
:HOST_PROJECT_ID=a-gcp-project-12345
You must set
HOST_PROJECT_ID
to the ID of the scoping project of a metrics scope (or the Workspace's host project). If it has any other value, then API commands to create or modify a dashboard fail with an error code of400
and a "not in Workspace" error message.Authenticate to Cloud SDK:
gcloud auth login
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 ${HOST_PROJECT_ID}
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.
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
resource. The common arguments include values specified by the
HOST_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/${HOST_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/${HOST_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]"
You must set HOST_PROJECT_ID
to the ID of the scoping project of a metrics scope (or the Workspace's host project).
If it has any other value, then API commands to create or modify
a dashboard fail with an error code of 400
and a "not in Workspace" error
message.
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/${HOST_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/${HOST_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/[HOST_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/${HOST_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/${HOST_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/${HOST_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/${HOST_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.