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