Create and manage dashboards by API

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

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 as STRING and also set the stringValue 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 as STRING_ARRAY and also set the stringArrayValue field. In the following example, there are three default values.
```
"valueType": "STRING_ARRAY",
"stringArrayValue": {
  "values": [ "a", "b", "c" ]
},
```
Note: If you don't specify a default value, then the wildcard operator, (*), is selected automatically. If you plan to use the variable in a logs panel, then you must use the regular expression as a comparator. For SQL queries, you must use an IF statement. For more information, see Charts with SQL queries.
Optional: To specify the list of all possible values for a value-only variable, set either the stringArray field or the timeSeriesQuery field. If you specify a query, it must be an analytics query.

Note: Don't set the timeSeriesQuery or stringArray fields when you create a pinned filter or a label-based variable. The set of all possible values is dynamically determined.

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. The valueType and stringValue fields specify the single default value. For more information, see the API references page for the dashboardFilters data structure.
The label-based variable has the name my_label_based_variable, and its label key is instance_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 name my_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 `instance_id`.
`${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 `instance_id`.
`${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 named log_name. Next, you create a chart, select Insert variable filter, and then select the variable LogName. The following code is generated:
```
WHERE IF(@LogName = '*', TRUE, LogName = @LogName)
```
In this example, you need to edit the generated code and replace LogName = with log_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

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
    }
  }
],

IF(ARRAY_LENGTH(CAST(@my_value_only_variable)) = 0, TRUE,
   severity IN UNNEST(@my_value_only_variable))

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 `instance_id`.
`${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 `instance_id`.
`${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 and name fields, and change the value of the displayName 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 the Dashboards 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 the Dashboards 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.

Create and manage dashboards by API

About dashboards

Dashboard layouts

Dashboard widgets

Dashboard labels

Dashboard filters

Create filters and variables

Console

API

General syntax to dereference a variable

Logs panel widgets

Console

API

Charts with PromQL queries

Console

API

Charts with SQL queries

Console

API

Charts with MQL queries

Console

API

Charts with Monitoring filter queries

Console

API

Create a dashboard

API

gcloud

Terraform

Delete dashboards

API

gcloud

Terraform

List dashboards

API

gcloud

Terraform

Paginate the list response

API

gcloud

Terraform

Get dashboard

API

gcloud

Terraform

Update dashboard

API

gcloud

Terraform

What's next