This document describes how you can create and manage
custom dashboards and the widgets on those dashboards by using
the Dashboard
resource in the Cloud Monitoring API.
The examples here illustrate how to manage your dashboards by using
curl
to invoke the API, and they show how to use the Google Cloud CLI.
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.
The endpoint supports the following methods for managing and configuring dashboards:
dashboards.create
: creates a 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
Google Cloud CLI.
You can't retrieve, edit, or delete predefined dashboards.
About dashboards
When creating a dashboard, you must specify which components, or widgets, you want to display, and the layout for those widgets. You can also add labels and filters to your dashboard. Labels can help you find a dashboard or indicate the type of content on the dashboard.
Dashboard layouts
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"
}
}
]
}
]
}
}
Dashboard 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 multiple types of Widget
objects:
XyChart
widget displays data over the X and Y axes.This widget displays a dataset that can be time-series data or generated by a SQL query. This widget lets you associate the charted data with either the left or right Y-axis. When multiple metric types are charted, you can use both Y-axes. The
XyChart
widget supports the following display styles:- Line charts
- Bar charts
- Stacked area charts
- Heatmaps
Widgets that display from one dimension, such as the latest value:
PieChart
: displays the latest values of a collection of time series, where each time series contributes one slice to the pie.Scorecard
: displays the latest value of one time series, and how this value relates to one or more thresholds.TimeSeriesTable
: displays the latest value, or an aggregated value, for each time series. Tables support customization. For example, you can color-code cells and configure column names and data alignment.
Widgets that display alerting policy or incident information:
AlertChart
: displays a summary of a single-condition alerting policy. This widget displays data as a line chart, shows the threshold, and lists the number of open incidents.IncidentList
: displays a list of incidents. You can configure the widget to show incidents for specific alerting policies or for specific resource types.
Widgets that display log entries and errors:
ErrorReportingPanel
: displays error groups that are stored in the selected Google Cloud project.LogsPanel
: displays project-scoped log entries that are stored in the current Google Cloud project. You can configure the widget to show log entries stored in Google Cloud projects accessible through the current metrics scope.
Text and organization widgets:
CollapsibleGroup
: displays a collection of widgets. You can collapse the view of a group.SingleViewGroup
: displays one widget in a collection of widgets. You can select which widget to display.SectionHeader
: creates a horizontal divider in your dashboard, and it creates an entry in the dashboard's table of contents.Text
: displays textual content, either as raw text or a Markdown string.
To include the text and organization widgets on a dashboard, the dashboard must have a
MosaicLayout
.
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 whose right Y-axis is configured:
{
"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 labels
Labels can help you manage and organize your dashboards. For example, you
might add a label named prod
to indicate that dashboard displays
time-series data and log data for your production resources. Alternatively,
you might add the label playbook
to indicate that the dashboard
contains information to help you troubleshoot failures.
Adding labels to a dashboard is optional.
For example, the following shows a Dashboard
object that
specifies the label named playbook
.
{
"displayName": "Example",
"mosaicLayout": {
"columns": 12,
"tiles": [
...
]
},
"dashboardFilters": [],
"labels": {
"playbook": ""
}
}
As the previous sample illustrates, the labels
field is implemented as a
map
, where the key
and value
fields are both strings. When you add a
label to a dashboard, set the key
to the name of the label, and set the
value
field to an empty string.
Dashboard filters and variables
When you design a dashboard, you might identify multiple ways to view the data the dashboard displays. For example, suppose a dashboard displays time-series data for your virtual machine (VM) instances. You might want to view the time-series data for all VMs, and you might want to view only that data that is in a specific zone. In this situation, we recommend that you create a pinned filter or a variable and then set the default value of that filter to the most commonly viewed zone.
Pinned filters apply to all dashboard widgets that support the label
specified in the filter, unless the widget contains a filter with that same
label key.
For example, when a chart includes the filter zone = us-central1-a
, that
chart ignores a pinned filter whose label key is zone
. Similarly,
this filter is ignored by charts that don't have a label with
a key of zone
.
Variables are like pinned filters, but they only apply to specific
widgets. Variables can be based on labels, like pinned filters are, or
they can have a value only. Value-only variables contain one or more
default values, and a list of all possible values. If you don't specify
a default value, then the default is set to the wildcard operator (*)
.
To define the set of all possible values, you either provide an array of
values or you write a SQL query.
For both pinned filters and variables, the dashboard toolbar displays
each variable, along with a menu, which lets you temporarily change the value of
the variable. The same data structure is used to represent pinned filters
and variables. For more information, see DashboardFilter
.
To learn how to apply a label-based variable or value-only variable to a widget, see the following sections:
- General syntax to dereference a variable
- Logs panel widgets
- Charts with PromQL queries
- Charts with SQL queries
- Charts with MQL queries
Charts with Monitoring filter queries
When you use the menu-driven interface to create a chart that displays time-series data, your selections are converted into a Monitoring filter.
Create filters and variables
Console
For information about how to use the Google Cloud console to create pinned filters and variables, see the following documents:
API
To define pinned filters and variables, use the
dashboardFilters
data structure.
- To create a variable, set the value of the
templateVariable
field to the name of the variable. Omit this field or set the value to an empty string when you want to create a pinned filter. - To create a pinned filter or a label-based variable, you must specify
the
labelKey
field. Omit this field when you want a value-only variable. Set the default value for the filter or variable. The configuration of this field determines whether a user can select exactly one option from the menu of value, or whether they can select multiple values.
- To set a single default value and to restrict users to selecting exactly
one option in the values menu, set the
valueType
field asSTRING
and also set thestringValue
field:
"valueType": "STRING", "stringValue": "my-default-value",
- To set at least one default value and to let users select multiple options
in the values menu, set the
valueType
field asSTRING_ARRAY
and also set thestringArrayValue
field. In the following example, there are three default values.
"valueType": "STRING_ARRAY", "stringArrayValue": { "values": [ "a", "b", "c" ] },
- To set a single default value and to restrict users to selecting exactly
one option in the values menu, set the
Optional: To specify the list of all possible values for a value-only variable, set either the
stringArray
field or thetimeSeriesQuery
field. If you specify a query, it must be an analytics query.
For example, consider the following dashboardFilters
object:
{ "dashboardFilters": [ { "labelKey": "zone" "stringValue": "us-central1-c", "valueType": "STRING", "filterType": "RESOURCE_LABEL" }, { "labelKey": "instance_id", "stringValue": "3133577226154888113", "valueType": "STRING", "filterType": "RESOURCE_LABEL", "templateVariable": "my_label_based_variable" }, { "filterType": "VALUE_ONLY", "templateVariable": "my_value_only_variable", timeSeriesQuery: { opsAnalyticsQuery: { sql: " SELECT log_name FROM `MY_TABLE` GROUP BY log_name ", } } } ], "displayName": "Illustrate Variables", ... }
The previous JSON defines one pinned filter and two variables:
The pinned filter has the label key of
zone
, which is is displayed on the toolbar. ThevalueType
andstringValue
fields specify the single default value. For more information, see the API references page for thedashboardFilters
data structure.The label-based variable has the name
my_label_based_variable
, and its label key isinstance_id
. The default value for this variable is set to a specific instance ID. You can also configure the default value by using an array. On the toolbar, the filter is displayed with the namemy_label_based_variable
.The value-only variable is named
my_value_only_variable
. This entry doesn't specify a default value, so the wildcard operator,(*)
, is automatically applied. Additionally, this variable uses a SQL query to generate the list of possible values for the variable.
Note that the dashboardFilters
object doesn't list the widgets to which the
variable applies. To apply a variable to a widget, you modify the
query for the widget.
General syntax to dereference a variable
For all widgets, except those that are defined by SQL, use the following syntax to apply a variable to a query:
To apply a label-based variable and have the label key and the label value resolved into a valid filter expression for the query language, use
${my_label_based_variable}
.To apply only the value of a label-based variable, use
${my_label_based_variable.value}
. The comparison must use a regular expression.To apply only the value of a value-only variable, use
${my_value_only_variable}
. For value-only variables, don't include a.value
clause. The comparison must use a regular expression.
Logs panel widgets
To apply a variable to a logs panel widget, update the queries pane. The syntax for these widgets follows that specified under General syntax.
Console
For example, the following query uses a regular expression to compare
the value of the jsonPayload.message
field with a string value that includes
the value of a label-based variable:
jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value}"
As another example, consider a value-only variable,
value_only_severity_variable
, and assume that in the menu of values, three
values are selected: ERROR
, INFO
, and NOTICE
.
Next, you add the following to the query pane of your logs panel widget:
severity =~ "${value_only_severity_variable}"
The following illustrates the rendered form:
severity =~ "^(ERROR|INFO|NOTICE)$"
API
For example, the following JSON illustrates how to apply a label-based variable to the query of a logs panel widget:
"logsPanel": { "filter": "${my_label_based_variable}", "resourceNames": [ "projects/1234512345" ] },
For example, the following query uses a regular expression to compare
the value of the jsonPayload.message
field with a string value that includes
the value of a label-based variable:
"logsPanel": { "filter": "resource.type=\"gce_instance\"\n resource.labels.project_id=~\"${my_label_based_variable.value}\"\n", "resourceNames": [ "projects/012345" ] }
As another example, consider a value-only variable,
value_only_severity_variable
, and assume that three
values are selected in the menu: ERROR
, INFO
, and NOTICE
.
Next, you add the following to the query pane of your logs panel widget:
"logsPanel": {
"filter": "severity =~ \"${value_only_severity_variable}\"\n",
...
}
The following illustrates the query as executed by the logs panel widget:
severity =~ "^(ERROR|INFO|NOTICE)$"
If you've configured a query for the logs panel and then select the button to open the Logs Explorer, the variables are resolved before the Logs Explorer is opened.
The following table illustrates how the example variables are are resolved by the logs panel. As previously mentioned, when only the value of a variable is used, you must use a regular expression as the comparison operator:
Syntax | Selected Value |
Resolved logs panel expression |
---|---|---|
${my_label_based_variable} |
12345 |
resource.labels."instance_id"="12345"
The example variable is based on the resource label
|
${my_label_based_variable} |
* |
"" |
${my_label_based_variable.value} ${my_value_based_variable} |
12345 |
12345 |
${my_label_based_variable.value} ${my_value_based_variable} |
* |
.* |
Charts with PromQL queries
To apply a label-based variable to a chart that has a PromQL query, follow the guidance listed in General syntax.
Console
For example, the following query relies on the label-based variable,
my_label_based_variable
, being resolved into a filter expression:
compute_googleapis_com:instance_cpu_utilization{ monitored_resource="gce_instance", ${my_label_based_variable} }
You can also modify query to resolve only the value of a variable.
The following example uses a regular expression to compare the value
of a label-based query to the instance_id
:
compute_googleapis_com:instance_cpu_utilization{ instance_id=~"${my_label_based_variable.value}" }
If you have a value-only variable, then omit the .value
clause. For example,
to filter by zone using a value-only variable, the query would include
something like the following:
zone=~"${my_value_only_variable}"
API
For example, the following JSON illustrates a query that relies on the
label-based variable,
my_label_based_variable
, being resolved into a filter expression:
"timeSeriesQuery": { "prometheusQuery": "avg_over_time( compute_googleapis_com:instance_cpu_utilization{ monitored_resource=\"gce_instance\", ${my_label_based_variable} }[${__interval}])", "unitOverride": "", "outputFullDuration": false },
You can also modify query to resolve only the value of a variable.
The following example uses a regular expression to compare the value
of a label-based query to the instance_id
:
"timeSeriesQuery": { "prometheusQuery": "avg_over_time( compute_googleapis_com:instance_cpu_utilization{ monitored_resource=\"gce_instance\", instance_id=~\"${my_label_based_variable.value}\" }[${__interval}])", "unitOverride": "", "outputFullDuration": false },
If you have a value-only variable, then omit the .value
clause. For example,
to filter by zone using a value-only variable, the query would include
something like the following:
zone=~\"${my_value_only_variable}\"
The following table illustrates how the example variables are are resolved by the PromQL. As previously mentioned, when only the value of a variable is used, you must use a regular expression as the comparison operator:
Syntax | Selected Value |
Resolved PromQL expression |
---|---|---|
${my_label_based_variable} |
12345 |
instance_id == '12345'
The example variable is based on the resource label
|
${my_label_based_variable} |
* |
noop_filter=~".*" |
${my_label_based_variable.value} ${my_value_based_variable} |
12345 |
12345 |
${my_label_based_variable.value} ${my_value_based_variable} |
* |
.+ |
Charts with SQL queries
When you want to apply a variable to a SQL-defined widget,
update the WHERE
clause to reference the value of the variable.
For all variables, prefix the variable name with the "at" sign, for example:
@variable_name
. For label-based variables, append .value
to the
variable name, @my_label_based_variabe.value
.
For SQL queries, the variable substitution relies on BigQuery, and is SQL-injection safe. For more information, see Running parameterized queries.
Console
Because SQL doesn't interpret the wildcard operator to mean "any value", we
recommend that you always use an IF
statement when applying
variables to a SQL query. The following example illustrates usage for
a value-only variable whose data type is a string:
WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)
When the menu option for the variable lets users select multiple values,
you must cast
the value of the variable to a GoogleSQL data type by using the
CAST
function.
The following query illustrates this syntax:
IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE, severity IN UNNEST(@my_value_only_variable))
The IF
statement shown in the previous examples is recommended because SQL
doesn't interpret the wildcard operator to mean "any value". Therefore, if you
omit the IF
statement and if you select the wildcard operator,
then the result of the query is an empty table. In the second example,
the UNNEST
function converts
the array to a table.
To add a properly-formatted WHERE
clause, do the following:
- Edit the widget.
- In the toolbar, select Insert variable filter, and then select the
variable that you want to apply to the
WHERE
clause. - In the dialog that opens, review the generated code and then click Copy and close.
Paste the copied code into the Query pane and make any necessary edits.
For example, suppose you create a variable named
LogName
that generates a list of log names and outputs the result in a table with a single column namedlog_name
. Next, you create a chart, select Insert variable filter, and then select the variableLogName
. The following code is generated:WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
In this example, you need to edit the generated code and replace
LogName =
withlog_name =
, so that the table join can occur:WHERE IF(@LogName = '*', TRUE, log_name = @LogName)
Click Run and then Apply.
To save your modified dashboard, in the toolbar, click Save.
API
Because SQL doesn't interpret the wildcard operator to mean "any value", we
recommend that you always use an IF
statement when applying
variables to a SQL query. The following example illustrates usage for
a value-only variable whose data type is a string:
WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable)
For example, the following shows a partial JSON representation of a chart
that displays the results of a SQL query. To support filtering the results
by the name of a log, a WHERE
clause was added that references the variable
named LogName
:
"plotType": "STACKED_BAR", "targetAxis": "Y1", "timeSeriesQuery": { "opsAnalyticsQuery": { "queryExecutionRules": {}, "queryHandle": "", "sql": "SELECT\n timestamp, severity, resource.type, log_name, text_payload, proto_payload, json_payload\n FROM\n `my-project.global._Default._Default`\n WHERE \n IF (@LogName = \"*\", TRUE, log_name=@LogName)\nLIMIT 10000" } }
The variable LogName
also issues a query to determine the list of
possible log names:
"dashboardFilters": [ { "filterType": "VALUE_ONLY", "templateVariable": "LogName", "valueType": "STRING", "timeSeriesQuery": { "opsAnalyticsQuery": { "savedQueryId": "", "sql": "SELECT log_name FROM `my-project.global._Default._Default` GROUP BY log_name LIMIT 1000", "queryHandle": "" }, "unitOverride": "", "outputFullDuration": false } } ],
When the menu option for the variable lets users select multiple values,
you must cast
the value of the variable to a GoogleSQL data type by using the
CAST
function.
The following query illustrates this syntax:
IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE, severity IN UNNEST(@my_value_only_variable))
The IF
statement shown in the previous examples is recommended because SQL
doesn't interpret the wildcard operator to mean "any value". Therefore, if you
omit the IF
statement and if you select the wildcard operator,
then the result of the query is an empty table. In the second example,
the UNNEST
function converts
the array to a table.
Charts with MQL queries
To apply a label-based variable to a chart that has a MQL query, append
a pipe, (|)
, and then follow the guidance listed in
General syntax.
When you use the menu-driven interface to create a chart that displays time-series data, your selections are converted into a Monitoring filter
Console
For example, the following query relies on a label-based variable,
my_label_based_variable
, being resolved into a filter expression:
fetch gce_instance | metric 'compute.googleapis.com/instance/cpu/utilization' | every 1m | ${my_label_based_variable}
You can also modify query to resolve only the value of a variable.
The following example uses a regular expression to compare the value
of a label-based query to the instance_id
:
fetch gce_instance | metric 'compute.googleapis.com/instance/cpu/utilization' | filter resource.instance_id=~'${my_label_based_variable.value}' | group_by 1m, [value_utilization_mean: mean(value.utilization)] | every 1m
If you have a value-only variable, then omit the .value
clause. For example,
to filter by zone using a value-only variable, the query would include
something like the following:
resource.zone=~'${my_value_only_variable}'
API
For example, the following JSON illustrates a query that relies on a
label-based variable,
my_label_based_variable
, being resolved into a filter expression:
"timeSeriesQuery": { "timeSeriesQueryLanguage": "fetch gce_instance\n | metric 'compute.googleapis.com/instance/cpu/utilization'\n | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n | every 1m\n | ${my_label_based_variable}", "unitOverride": "", "outputFullDuration": false },
You can also modify query to resolve only the value of a variable.
The following example uses a regular expression to compare the value
of a label-based query to the instance_id
:
"timeSeriesQuery": { "timeSeriesQueryLanguage": "fetch gce_instance\n | metric 'compute.googleapis.com/instance/cpu/utilization'\n | filter resource.instance_id=~'${my_label_based_variable.value}'\n | group_by 1m, [value_utilization_mean: mean(value.utilization)]\n | every 1m\n", "unitOverride": "", "outputFullDuration": false },
If you have a value-only variable, then omit the .value
clause. For example,
to filter by zone using a value-only variable, the query would include
something like the following:
resource.zone=~'${my_value_only_variable}'
The following table illustrates how the example variables are are resolved by the MQL. As previously mentioned, when only the value of a variable is used, you must use a regular expression as the comparison operator:
Syntax | Selected Value |
Resolved MQL expression |
---|---|---|
${my_label_based_variable} |
12345 |
filter (resource.instance_id == '12345')
The example variable is based on the resource label
|
${my_label_based_variable} |
* |
filter (true) |
${my_label_based_variable.value} ${my_value_based_variable} |
12345 |
12345 |
${my_label_based_variable.value} ${my_value_based_variable} |
* |
.* |
Charts with Monitoring filter queries
To apply a label-based variable to a chart that has a query in the form of a Monitoring filter, follow the guidance listed in General syntax.
Console
If you use the Google Cloud console to create your charts, and if you use the menu-driven interface, then you can apply a label-based variable to a chart by using the variable's Apply to charts field or by editing the widget and selecting label-based variable from the Filter menu. The Filter menu lists all label-based variables and all label keys.
To apply a value-based variable to these types of charts, do the following:
- Edit the chart.
- In the query pane, click Add filter and select a label key. For example, you might select zone.
- In the Value menu, select your value-only variable.
- Click Apply.
- To save your modified dashboard, in the toolbar, click Save.
For example, the following JSON illustrates a query that relies on a
label-based variable,
my_label_based_variable
, being resolved into a filter expression:
metric.type="compute.googleapis.com/instance/cpu/utilization" resource.type="gce_instance" ${my_label_based_variable}"
Widgets that use a query in the form of a Monitoring filter
can't filter the time series by the value in a label-based variables;
however, you can filter by value-only variables.
For example, the following query shows the value of the Filters field
of a query that filters by zone
, based on the value of a value-only variable:
metric.type="compute.googleapis.com/instance/cpu/utilization" resource.type="gce_instance" resource.label."zone"=monitoring.regex.full_match(${my_value_only_variable})
API
For example, the following JSON illustrates a query that relies on a
label-based variable,
my_label_based_variable
, being resolved into a filter expression:
"timeSeriesQuery": { "timeSeriesFilter": { "filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" ${my_label_based_variable} ", "aggregation": { "alignmentPeriod": "60s", "perSeriesAligner": "ALIGN_MEAN", "groupByFields": [] } }, "unitOverride": "", "outputFullDuration": false },
Widgets that use a query in the form of a Monitoring filter
can't filter the time series by the value in a label-based variables;
however, you can filter by value-only variables.
For example, the following query shows the "filter"
field of a query that
filters by zone
, based on the value of a value-only variable:
"filter": "metric.type=\"compute.googleapis.com/instance/cpu/utilization\" resource.type=\"gce_instance\" resource.labels.\"zone\"=monitoring.regex.full_match(${my_value_only_variable})"
The following table illustrates how the example variables are are resolved by the Monitoring filter. As previously mentioned, when only the value of a variable is used, you must use a regular expression as the comparison operator:
Syntax | Selected Value |
Resolved filter expression |
---|---|---|
${my_label_based_variable} |
12345 |
resource.instance_id == "12345"
The example variable is based on the resource label
|
${my_label_based_variable} |
* |
Omitted |
${my_label_based_variable.value} |
12345 |
Not supported |
${my_label_based_variable.value} |
* |
Not supported |
${my_value_based_variable} |
12345 |
"12345" |
${my_value_based_variable} |
* |
".*" |
Create 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/${PROJECT_ID}/dashboards/${DASHBOARD_ID}"
API
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 example, if you want to duplicate a dashboard, do the following:
- Complete the steps in Get dashboard to download the definition of the original dashboard.
- Edit the returned JSON to remove the
etag
andname
fields, and change the value of thedisplayName
field. - Run the command to create the dashboard.
For more information, see the gcloud monitoring dashboards
create
reference.
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands. For more information, see the Terraform provider reference documentation.
To create a dashboard by using Terraform, use the Terraform resource
google_monitoring_dashboard
.
In the command, set the following fields:
dashboard_json
: The JSON representation of the dashboard, using theDashboards
format.For examples of this format, you can either list your dashboards by using the APIs Explorer, or you can open a dashboard in the Google Cloud console, and view the JSON representations.
parent
: The fully-qualified name of your project. For example, you might set this field to"projects/PROJECT_ID"
, where PROJECT_ID is the ID of your Google Cloud project.
The examples create a sample dashboard by using the my-dashboard.json
file.
You can manage your dashboard through the
Google Cloud console.
For additional dashboard configurations, see Example dashboards and layouts.
Delete dashboards
To delete a custom dashboard, invoke the
dashboards.delete
method and specify the dashboard you want to delete.
API
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/${PROJECT_ID}/dashboards/${DASHBOARD_ID}
For more information, see the gcloud monitoring dashboards
delete
reference.
Terraform
You can delete resources by using Terraform. For information about deleting resources, see the Terraform command destroy.
List dashboards
To list all custom dashboards that belong to a project, invoke the
dashboards.list
method and specify the project ID.
API
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.
Terraform
You can't use Terraform to send a query your project with the response being a list of dashboards. However, you can view these dashboards by using the Google Cloud console.
The examples return the custom dashboards associated with your project.
Paginate the list response
The dashboards.list
method supports pagination, which
lets you take the results one page at a time instead of all at once.
API
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 page, 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
Terraform
You can't use Terraform to send a query your project with the response being a paginated list of dashboards. However, you can view these dashboards by using the Google Cloud console.
Get dashboard
To get a specific custom dashboard for a project, invoke the
dashboards.get
method, qualified with the dashboard ID.
API
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.
Terraform
You can't use Terraform to send a query your project with the response being an individual dashboard. However, you can view these dashboards by using the Google Cloud console.
Update dashboard
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.
API
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}
The previous example updates an existing custom dashboard using the
my-updated-dashboard.json
file. The response, which includes a new
etag
value, is a copy of the updated dashboard listing.
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 previous example updates an existing custom dashboard using the
my-updated-dashboard.json
file. The response, which includes a new
etag
value, is a copy of the updated dashboard listing.
Terraform
To learn how to apply or remove a Terraform configuration, see Basic Terraform commands. For more information, see the Terraform provider reference documentation.
To update a dashboard by using Terraform, use the Terraform resource
google_monitoring_dashboard
.
In the command, set the following fields:
dashboard_json
: The JSON representation of the dashboard, using theDashboards
format.parent
: The fully-qualified name of your project. For example, you might set this field to"projects/PROJECT_ID"
, where PROJECT_ID is the ID of your Google Cloud project.