Create a Query-based Widget Using Metrics

You can create a query-based widget using 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:

Go to the Dashboards page.
Click Create dashboard to create a new dashboard or open an existing dashboard in edit mode.
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.
On the Widgets tab, click the Add widget group and widgets icon () and click Create query-based widget....
The query-based widget builder is displayed.
Optionally, click the Open/close filter panel icon () 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 the upper-right corner, select a time period for which you want to display data in the widget.
Select Monitoring in the Data source field.
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 build 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.
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 building 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()
```
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 specify or edit the details on the About, Visualization, and Settings tabs, in a JSON editor. 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:
  - Tagging concepts and the permissions required to work with tags, see Overview of Tagging.
  - How to add a tag during resource creation, see To add a tag during resource creation.
- Visualization: Select a chart type and customize the visualization by specifying or modifying additional options.
  If you select Table as the chart type, then you have the option of removing some of the columns or select the All columns check box to display all columns. Chart types that have X and Y axes, such as the Line chart have a combination of the following additional visualization options:
  - X axis: Select the data attribute you want projected on the X axis. In the X axis you can opt to display the name of the metric, namespace, and so on.
  - Y axis: Select the data attribute you want projected on the Y axis. Y axis supports numeric data attributes and only those are listed.
  - Series: Select the data attribute that you want to plot in separate series in the chart. To use this option, add the groupBy clause with a dimension in the query and view separate series for the various values of that dimension. For example, in the following query, the CPU utilization metric in the oracle_oci_database namespace is grouped by the resourceName dimension and separate series are displayed for each of the resources.
```
CpuUtilization[auto].groupBy(resourceName).mean()
```
    This option is also available for a Pie chart.
  - Size: Select a data attribute to whose values you want to assign size. This option is only available for a Bubble chart.
  - Color by: Select the data attribute to whose values you want to assign distinct colors. Typically, the Color by option is used along with the Series option to assign distinct colors to the separate series. This option is also available for a Pie chart.
  - X axis title: Specify a title for the data attribute projected on the X axis.
  - Y axis title: Specify a title for the data attribute projected on the Y axis.
  - Legend: Specify the location of the legend in the widget. This option is also available for a Pie chart.
  - Correlated tooltips: Select this option to correlate the tooltips across all your query-based widgets in the dashboard.
  - Data cursor: Select this option to view the tooltip when you hover the mouse over the widget.
  - Stacked: Select this option if you want to stack the data attributes displayed in the chart, by color.
  - Use solid color: When you use an Area chart for visualization, the area that represents the presence of data is covered in solid color. This option is selected by default.
  For more information on the visualization options in a query-based widget builder, see About Visualization Options.
- Settings: Review and edit widget inputs, if required.
Click Save to save the widget in the widget library and add it to the dashboard.

Oracle Cloud Infrastructure Documentation