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 .

This feature is supported only for Google Cloud projects. For App Hub configurations, select the App Hub host project or management project.

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 widgets that query data, you can include a variable in the widgets's query and you can use a variable to control the visibility of the widget. When the query depends on a variable, the data the widget requests changes when you change the value of the variable. As a result, the displayed data also changes. When you use a variable to control the visibility of a widget, a visibility Visibleicon is shown in the toolbar. For restrictions related to visibility, see Set the visibility of a widget .

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. To help you differentiate filters from variables, in the dashboard toolbar, the name of a variable is prepended with a dollar sign $ . For more information, see DashboardFilter .

For an example that shows how you can control the visibility of widget by using a variable, see Dashboard with widget-visibility configured .

To learn how to update the query of a widget with a label-based variable or value-only variable, see the following sections:

• General syntax to dereference a variable
• Logs panel widgets
• Charts with PromQL queries
• Charts with SQL 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

{
  "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",
  ...
}

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 .

jsonPayload.message=~"Connected to instance: ${my_label_based_variable.value} 
"

 severity =~ "${value_only_severity_variable}" 

 severity =~ "^(ERROR|INFO|NOTICE)$" 

"logsPanel": {
  "filter": " ${my_label_based_variable} 
",
  "resourceNames": [
    "projects/1234512345"
  ]
},

"logsPanel": {
  "filter": "resource.type=\"gce_instance\"\n
             resource.labels.project_id =~\"${my_label_based_variable.value}\" 
\n",
  "resourceNames": [
    "projects/012345"
  ]
}

 "logsPanel": {
  "filter": "severity =~ \"${value_only_severity_variable}\"\n",
  ...
} 

 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:

Charts with PromQL queries

To update a chart that has a PromQL query to depend on a label-based variable, follow the guidance listed in General syntax .

compute_googleapis_com:instance_cpu_utilization{
    monitored_resource="gce_instance", ${my_label_based_variable} 
}

compute_googleapis_com:instance_cpu_utilization{
    instance_id =~"${my_label_based_variable.value}" 
}

zone =~"${my_value_only_variable}" 

"timeSeriesQuery": {
  "prometheusQuery": "avg_over_time(
    compute_googleapis_com:instance_cpu_utilization{
      monitored_resource=\"gce_instance\", ${my_label_based_variable} 
}[${__interval}])",
  "unitOverride": "",
  "outputFullDuration": false
},

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

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:

Charts with SQL queries

When you want to update a SQL-defined widget to depend on a variable, 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 .

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable) 

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

WHERE IF(@my_value_only_variable = "*", TRUE, log_name = @my_value_only_variable) 

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

"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 Monitoring filter queries

To update a chart that has a query in the form of a Monitoring filter to depend on a label-based variable, follow the guidance listed in General syntax .

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance" ${my_label_based_variable} 
"

metric.type="compute.googleapis.com/instance/cpu/utilization"
resource.type="gce_instance"
resource.label."zone"= monitoring.regex.full_match(${my_value_only_variable}) 

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

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

Before you begin

Complete the following in the Google Cloud project where you want to create or manage dashboards:

• Select the tab for how you plan to use the samples on this page:

  gcloud

  In the Google Cloud console, activate Cloud Shell.

  Activate Cloud Shell

  At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

  Terraform

  To use the Terraform samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

  If you're using a local shell, then create local authentication credentials for your user account:

  gcloud  
  auth  
  application-default  
  login

  You don't need to do this if you're using Cloud Shell.

  If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity .

  For more information, see Set up ADC for a local development environment in the Google Cloud authentication documentation.

  REST

  To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.

  Install the Google Cloud CLI.

  If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .

  For more information, see Authenticate for using REST in the Google Cloud authentication documentation.

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.

The name field is optional. The value of the name field has the following structure:

"name": "projects/ PROJECT_ID_OR_NUMBER 
/dashboards/ DASHBOARD_ID 
"

When you create a dashboard, the API automatically generates the DASHBOARD_ID component. If you want to specify a custom DASHBOARD_ID , then you can specify the name field of the Dashboard object.

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

 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 

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.

 gcloud  
monitoring  
dashboards  
delete  
 DASHBOARD_ID 
  
--project = 
 PROJECT_ID 
 

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

List dashboards

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

 gcloud  
monitoring  
dashboards  
list  
--project = 
 PROJECT_ID 
 

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

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.

 gcloud  
monitoring  
dashboards  
list  
--page-size = 
 1 
  
--project = 
 PROJECT_ID 
 

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

{
  "dashboards" : [
    {
       "displayName" : "Grid Layout Example",
       "gridLayout" : {
         "widgets" : [
            { ... },
            { ... },
            { ... },
          ]
       }
    }
  ]
},
"nextPageToken": "ChYqFDEyMzkzMzUwNzg0OTE1MDI4MjM3"

Get dashboard

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

 gcloud  
monitoring  
dashboards  
describe  
 DASHBOARD_ID 
  
--format = 
json  
--project = 
 PROJECT_ID 
 

{
  "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"
}

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

{
  "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"
}

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.

 gcloud  
monitoring  
dashboards  
update  
 DASHBOARD_ID 
  
--config-from-file = 
my-updated-dashboard.json  
--project = 
 PROJECT_ID 
 

 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 
 } 
 

What's next

• Example dashboards and layouts
• Create and manage custom dashboards with the Google Cloud console