Oracle Cloud Infrastructure Documentation

Create a Query-based Widget Using Metrics

You can create a query-based widget using the Oracle Cloud Infrastructure Monitoring service metrics.

Note

To create a query-based widget that displays Monitoring service metrics, you must have the required Monitoring service permissions. For information, see Get Started with Management Dashboard.

To create a query-based widget that displays Monitoring service metrics:

  1. Go to the Dashboards page.
  2. Click Create dashboard to create a new dashboard or open an existing dashboard in edit mode.
  3. Optionally, add the Metric dimension filter to the dashboard.

    You can use the Metric dimension filter to specify metric dimension input for a query-based widget. For information, see Use the Metric Dimension Filter.

  4. On the Widgets tab, click the Add widget group and widgets icon (Add widget group and widgets) and click Create query-based widget....
    The query-based widget builder is displayed.
  5. Optionally, click the Open/close filter panel icon (Open/close filter panel) to view the filters added to the dashboard and make changes, if required.

    Note that when creating a query-based widget to add it to a brand new dashboard, a Compartment filter is automatically added and the compartment input for the new widget being created is linked to this newly added filter. In addition, the Subcompartments check box is displayed in the Compartment filter, and you can select it to display metric data from all the sub-compartments within the root compartment. The option to view metric data from the sub-compartments can only be used if the root compartment is selected in the Compartment filter.

  6. In the upper-right corner, select a time period for which you want to display data in the widget.
  7. Select Monitoring in the Data source field.
  8. Specify the following Monitoring service metric details:
    1. Namespace: Select the applicable namespace.
    2. Resource group: Optionally, select a resource group, if available. A resource group is a custom string provided with a custom metric and can be used as a filter or to aggregate results.
    3. Query: Edit the default query displayed in this field or enter a brand new query to retrieve the metric information you want to display in the widget.

      The queries used to create query-based widgets use MQL syntax (METRIC[auto].grouping().mean()), which governs expressions for querying metrics that are published to the Monitoring service. For information, see Monitoring Query Language (MQL) Reference.

    4. Click Run.

    The query is executed and the metric data is displayed in a tabular format with the name of the metric, time stamp, and value. Below the Table chart, another table with the raw data returned by the query is displayed and you can click Hide raw data to hide it.

  9. Optionally, add input parameters to make the widget reusable by supplying different values of that parameter. For example, input parameters can be configured to filter the data by a specific dimension, where the value is supplied through the parameter. If you're creating a query-based widget for the Database Management service (oracle_oci_database namespace) to view CPU utilization (CpuUtilization metric), you can add an input parameter using the resourceName dimension and configure dimension values to view the CPU utilization data for specific resources in the widget.
    1. On the Settings tab, click Add input +.
    2. In the Configure input for untitled widget (optional) dialog box:
      1. Input name: Enter a name for the input parameter. For example, if you want to add the resourceName dimension as an input parameter for the widget, the Input name could be resourcename. Note that the input name is required when adding a placeholder expression to the query.
      2. Input label: Enter a display name for the input. The input name is displayed in this field by default and you can change it to make it more user-friendly.
      3. Default settings: Review and make changes to the default settings, if required.
        Note

        If you update the Default settings to configure the input parameter, the same settings will be applied whenever this widget is added to a different dashboard. To configure an input parameter whose value can be edited after the widget is created and added to the widget library, use the options in the Configure widget input section of this dialog box.
        • Required: Select to indicate that this is a required widget input. If you select this check box and do not configure the input parameter, data will not be displayed in the widget.
        • Allow multiple values: Select to allow multiple values to be configured for the input parameter.
        • Allow widget users to link the <name> input with a filter: Deselect this check box to only specify a fixed input parameter value. This check box is selected by default and if you deselect it, the fields available to link the input to a filter are not displayed in the dialog box.
        • Allow widget users to specify the <name> input: Deselect this check box to only link the input to a filter. This check box is selected by default and if you deselect it, the fields available to specify a fixed input parameter value are not displayed in the dialog box.
      4. Configure widget input: Select from the following options to configure the input parameter:
        • Link the input with an existing filter: Select to link the input parameter to an existing filter in the widget.
        • Specify the input: Select to specify a fixed input parameter value, which will be used only in the context of this widget.
        • Not configured: Select to leave the input unconfigured.
    3. Add a placeholder to the query to display the data from the additional input parameter in the widget, using the following expression: 
      {<dimension>=$(params.<input_name>)}

      Taking the same example mentioned at the beginning of step 8, after an input parameter was added for the resourceName dimension, the following placeholder expression (in bold) must be added to the CpuUtilization query to filter data by resource in the widget: 

      CpuUtilization[auto]{resourceName=$(params.resourcename)}.mean()
  10. Use the following tabs on the right side to perform tasks such as adding a name for the widget and customizing the visualization of data in the widget:
    Note

    You can click JSON in the upper-right corner to edit the JSON metadata of the widget directly. The JSON editor provides you with greater flexibility and more options to visualize data in the widget, however, it's recommended that you use it only if you're familiar with editing widget JSON. For more information on the JSON editor, contact Oracle Support.
    • About: Enter a name for the widget, select the compartment in which you want the widget to reside, and add a description for the widget.

      Optionally, click Show advanced options to add free-form or defined tags to the widget. If you have the permissions required to create a widget, then you also have permissions to add free-form tags. To add a defined tag, you must have permissions to use the tag namespace. For information on:

    • Visualization: Select a chart type and customize visualization by specifying or modifying additional options.

      For information on the chart types and visualization options in a query-based widget builder, see About Chart Types and Visualization Options.

    • Settings: Review and edit widget inputs, if required.
  11. Click Save to save the widget in the widget library and add it to the dashboard.

Display Metric Data from Multiple Regions

You can retrieve and display metric data from more than one region when creating a query-based widget using the Oracle Cloud Infrastructure Monitoring service metrics.

By default, a widget with the Region input responds to the top-level region selected in the Oracle Cloud Infrastructure console.

Here's a scenario in which a query-based widget is created to display metric data for resources such as Autonomous AI Databases, in different regions:

  1. Go to the query-based widget builder.
  2. Select a time period and the Monitoring service metric details.
  3. On the About tab, enter a name for the widget, select the compartment in which you want the widget to reside, and add a description for the widget.
  4. On the Settings tab, click the Edit Region input icon (Edit Region input).
  5. In the Configure Region input for <name of widget> (optional) dialog box:
    1. Expand Default settings and select the Allow multiple values check box.
    2. Select the regions from which you want to retrieve metric data in the Enter or select a default value drop-down list.
    3. Click Save changes.
  6. On the Visualization tab:
    1. Select a chart type such as a Line chart, which allows you to select data attributes in the Series drop-down list.
    2. Select the _regionName data attribute in the Series drop-down list to plot the metric data displayed in the widget by region.
    3. Select the _regionName data attribute in the Color by drop-down list to assign distinct colors to each region.
    4. Select an option in the Legend drop-down list to view a list of the different regions from which metric data is being retrieved and displayed.
  7. Click Save to save the widget in the widget library and add it to the dashboard.

Once the query-based metric widget is added to the dashboard, you can add the Region filter and link the Region input to the filter to have the widget respond to filter selections. To do so:

  1. On the Filters tab in the dashboard, click Add filters.
  2. Search for the Region filter and add it to the dashboard.
  3. On the Filters tab, click Edit filters.
  4. Edit the Selection mode input.

    The Configure Selection mode input for Region (optional) dialog box is displayed.

  5. Select Multiple in the Specify the Selection mode input drop-down list and click Save changes.
  6. Select the regions in the Region filter.
  7. On the Widgets tab, click Edit widgets.
  8. Edit the Region input for the query-based metric widget.

    The Configure Region input for <name of widget> dialog box is displayed.

  9. Select Link the Region input with an existing filter and then select Region from the Select an existing filter drop-down list.

The Region input for the query-based metric widget is linked to the Region filter and any changes made to the regions selected in the filter will change the data displayed in the widget.