# Creating flexible CloudWatch dashboards with dashboard variables
<a name="cloudwatch_dashboard_variables"></a>

Use *dashboard variables* to create flexible dashboards that can quickly display different content in multiple widgets, depending on the value of an input field within the dashboard. For example, you can create a dashboard that can quickly switch between different Lambda functions or Amazon EC2 instance IDs, or one that can switch to different AWS Regions.

After you create a dashboard that uses a variable, you can copy the same variable pattern to other existing dashboards.

Using dashboard variables improves the operational workflow for people who use your dashboards. It can also reduce your costs because you're using dashboard variables in one dashboard instead of creating multiple similar dashboards. 

**Note**  
If you share a dashboard that contains dashboard variables, the people that you share it with won't be able to change between the variable values.

## Types of dashboard variables
<a name="cloudwatch_dashboard_variables_types"></a>

The dashboard variable can be a *property variable* or a *pattern variable*.
+ *Property variables* change all instances of a property in all widgets in the dashboard. This property can be any JSON property in the JSON source of a dashboard, such as `region`. Or it can be a dimension name for a metric, such as `InstanceID` or `FunctionName`.

  For a tutorial that uses a property variable, see [Tutorial: Creating a CloudWatch Lambda dashboard with function name as the variable](cloudwatch_dashboard_variables_property.md). 

  For more information about the JSON source of dashboards, see [Dashboard Body Structure and Syntax](https://docs.aws.amazon.com/AmazonCloudWatch/latest/APIReference/CloudWatch-Dashboard-Body-Structure.html). In the CloudWatch console, you can see the JSON source for any custom dashboard by choosing **Actions**, **View/edit source**.
+ *Pattern variables* use a regular expression pattern to change all of a JSON property or only a certain part of it.

  For a tutorial that uses a pattern variable, see [Tutorial: Creating a dashboard that uses a regular expression pattern to switch between AWS Regions](cloudwatch_dashboard_variables_pattern.md).

Property variables apply to most use cases and are less complex to set up.

**Topics**
+ [Types of dashboard variables](#cloudwatch_dashboard_variables_types)
+ [Copying a variable to another CloudWatch dashboard](cloudwatch_dashboard_variables_copy.md)
+ [Tutorial: Creating a dashboard that uses a regular expression pattern to switch between AWS Regions](cloudwatch_dashboard_variables_pattern.md)
+ [Tutorial: Creating a CloudWatch Lambda dashboard with function name as the variable](cloudwatch_dashboard_variables_property.md)

# Copying a variable to another CloudWatch dashboard
<a name="cloudwatch_dashboard_variables_copy"></a>

After you create a dashboard with useful variables, you can copy these variables to other existing dashboards. For more information about dashboard variables, see [Creating flexible CloudWatch dashboards with dashboard variables](cloudwatch_dashboard_variables.md).

**To copy a dashboard variable to another dashboard**

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1.  In the navigation pane, choose **Dashboards**, and then choose the name of the dashboard that has the variable that you want to copy. Enter a string to find dashboards with matching names, if needed. 

1. Choose **Actions**, **Variables**, **Manage variables**.

1. Choose the radio button next to the variable that you want to copy, and choose **Copy to another dashboard**.

1. Choose the selection box and start typing the dashboard name that you want to copy the variable to.

1. Select the dashboard name and choose **Copy variable**.

# Tutorial: Creating a dashboard that uses a regular expression pattern to switch between AWS Regions
<a name="cloudwatch_dashboard_variables_pattern"></a>

The steps in this procedure illustrate how to create a flexible dashboard that can switch between Regions. This tutorial uses a regular expression *pattern variable* instead of a property variable. For a tutorial that uses a property variable, see [Tutorial: Creating a CloudWatch Lambda dashboard with function name as the variable](cloudwatch_dashboard_variables_property.md). 

For many use cases, you can create a dashboard that switches between Regions by using a property variable. But if the widgets rely on Amazon Resource Names (ARNs) that include Region names, you must use a pattern variable to change the Region names within the ARNs.

**To use a dashboard pattern variable to create a flexible multi-Region dashboard**

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1.  In the navigation pane, choose **Dashboards**, **Create dashboard**. 

1.  Enter a name for the dashboard, and choose **Create dashboard**. 

1.  Add widgets to the dashboard. When you add the widgets that you want to display Region-specific data, avoid specifying any dimensions with values that appear in only one Region. For example, for Amazon EC2 metrics, specify metrics that are aggregated instead of metrics that use **InstanceID** as a dimension. 

   For more information about adding widgets to a dashboard, see [Using widgets on CloudWatch dashboards](create-and-work-with-widgets.md).

1. After you add the widgets, as you are viewing the dashboard, choose **Actions**, **Variables**, **Create a variable**.

1. Choose **Pattern variable**.

1. For **Property that the variable changes**, enter the name of the current dashboard Region, such as **us-east-2**.

   You have the correct Region entered if the label below that box displays the widgets that will be impacted by the variable.

1. For **Input type**, for this use case, select **Radio button**. 

1. For **Define how inputs are populated**, choose **Create a list of custom values**.

1. For **Create your custom values**, enter the Regions that you want to switch between, with one Region on each line. After each Region, enter a comma and then the label to display for that radio button. For example:

   **us-east-1, N. Virginia**

   **us-east-2, Ohio**

   **eu-west-3, Paris**

   As you fill in the custom values, the **Preview** pane updates to display what the radio buttons will look like.

1. (Optional) For more settings, choose **Secondary settings** and do one or more of the following:
   + To customize the name of your variable, enter the name in **Custom variable name**.
   + To customize the label for the variable input field, enter the label in **Input label**. For this tutorial, enter **Region:**.

     If you enter a value here, the **Preview** pane updates to display what the radio buttons will look like.
   + To set the default value for this variable when the dashboard is first opened, enter the default in **Default value**.

1. Choose **Add variable**.

   The dashboard appears, with a **Region:** label next to the radio buttons for the Regions near the top. When you switch between Regions, all the widgets that use the variable will display information about the selected Region.

# Tutorial: Creating a CloudWatch Lambda dashboard with function name as the variable
<a name="cloudwatch_dashboard_variables_property"></a>

The steps in this procedure illustrate how to create a flexible dashboard that shows a variety of metric graphs, using a property variable. This includes a dropdown selection box on the dashboard that you can use to switch the metrics in all the graphs between different Lambda functions. 

Other use case examples for this type of dashboard include using `InstanceId` as the variable to create a dashboard of metrics with a dropdown for instance IDs. Alternatively, you could create a dashboard that uses `region` as the variable to display the same set of metrics from different Regions.

**To use a dashboard property variable to create a flexible Lambda dashboard**

1. Open the CloudWatch console at [https://console.aws.amazon.com/cloudwatch/](https://console.aws.amazon.com/cloudwatch/).

1.  In the navigation pane, choose **Dashboards**, **Create dashboard**. 

1.  Enter a name for the dashboard, and choose **Create dashboard**. 

1.  Add widgets to the dashboard that display metrics for a Lambda function. When you create these widgets, specify **Lambda**, **By Function Name** for the widget metrics. For the function, specify one of the Lambda functions that you want to include in this dashboard. 

   For more information about adding widgets to a dashboard, see [Using widgets on CloudWatch dashboards](create-and-work-with-widgets.md).

1. After you add the widgets, as you are viewing the dashboard, choose **Actions**, **Variables**, **Create a variable**.

1. Choose **Property variable**.

1. For **Property that the variable changes**, choose **FunctionName**.

1. For **Input type**, for this use case, we recommend choosing **Select menu (dropdown)**. This creates a dropdown menu in the dashboard where you can select the Lambda function name to display metrics for.

   If this was for a dashboard that toggled between only two or three different values for a variable, then **Radio button** would be a good choice.

   If you prefer to enter or paste in values for the variable, you would choose **Text input**. This option doesn't include a dropdown list or radio buttons. 

1. When you choose **Select menu (dropdown)**, you must then choose whether to populate the menu by entering values, or using a metric search. For this use case, let's assume that you have a large number of Lambda functions and you don't want to enter all of them manually. Choose **Use the results of a metric search** and then do the following:

   1. Choose **Pre-built queries**, **Lambda**, **Errors**. 

      (Choosing **Errors** does not add the **Errors** metric to the dashboard. However, it quickly populates the **FunctionName** variable selection box.)

   1. Choose **By Function Name** and then choose **Search**.

      Under the **Search** button, you will then see **FunctionName** selected. You also see a message about how many **FunctionName** dimension values were found to populate the input box.

1. (Optional) For more settings, choose **Secondary settings** and do one or more of the following:
   + To customize the name of your variable, enter the name in **Custom variable name**.
   + To customize the label for the variable input field, enter the label in **Input label**.
   + To set the default value for this variable when the dashboard is first opened, enter the default in **Default value**.

1. Choose **Add variable**.

   A **FunctionName** dropdown selection box appears near the top of the dashboard. You can select a Lambda function in this box and all the widgets that use the variable will display information about the selected function.

   Later, if you add more widgets to the dashboard that watch Lambda metrics with the **FunctionName** dimension, they will automatically use the variable.