Selecting Dimensions for a Query
Limit returned metric data by selecting dimensions when querying metric data in Monitoring. A dimension is a qualifier provided in a metric definition. In MQL, the dimension selection component specifies name-value pairs for dimensions, surrounded by curly brackets.
For query troubleshooting, see Troubleshooting Queries.
Considerations
Any text is accepted as a dimension name. If the dimension doesn't exist, then data isn't filtered.
To ensure that the dimension exists, list dimensions for the metric name or see Supported Services
Quotes around the value (as in
"FAULT-DOMAIN-1") can be omitted unless the value contains spaces or is used in Fuzzy Matching.- Example 1: Fault Domain
-
CpuUtilization[1m]{faultDomain = "FAULT-DOMAIN-1"}.mean() - Example 2: Compartment
-
IopsRead[1m]{compartmentId="ocid1.compartment.oc1.phx..exampleuniqueID"}.grouping().max() - Example 3: Shape (with Grouping)
-
CpuUtilization[1m]{shape="VM.Standard.E4.Flex"}.groupBy(availabilityDomain,poolId).mean() - Example 4: Multiple Dimension Name-Value Pairs: Fault Domain, Name, and Shape
-
CpuUtilization [1m]{faultDomain = "FAULT-DOMAIN-1", resourceDisplayName = "test", shape = "myshape"}.mean() - Example 5: Multiple Values for a Dimension: Fault Domain 1 or 2
-
CpuUtilization [1m]{faultDomain =~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean()
Specify approximate ("fuzzy") matches to dimension values in an MQL expression.
Fuzzy matching is available in MQL expressions only. In the Console, use Advanced mode.
In place of the equals sign (=) between the dimension name and set of values, use the following comparison operator.
| Comparison operator | Description |
|---|---|
=~ (equals sign followed by tilde) |
Approximately equal to. Use for fuzzy matches |
For fuzzy matching, surround the set of values with quotes: name = "val*" or name = "value1|value2"
Update the set of values using one or more of the following characters.
| Value Fuzzy Match Character | Description |
|---|---|
* (asterisk) |
Wildcard, indicating zero to many characters. |
|(pipe) |
OR operand for dimension values. |
Example showing fuzzy matching for three dimension value sets (test compute instances in fault domain 1 that use the myshape shape):
CpuUtilization [1m]{faultDomain =~ "FAULT-DOMAIN-1", resourceDisplayName =~ "test*", shape =~ "myshape"}.mean() Filter out (exclude) dimension values in an MQL expression.
Excluding values is available in MQL expressions only. In the Console, use Advanced mode.
In place of the equals sign (=) between the dimension name and set of values, use one of the following comparison operators.
| Comparison operator | Description |
|---|---|
!= (exclamation point followed by equals sign) |
Not equal to. Use to filter out a single dimension value. |
!~ (exclamation point followed by tilde) |
Not equal to. Use to filter out multiple dimension values (when the expression uses wildcards or OR operands). |
If using the !~ comparison operator, then update the set of dimension values using one or more of the following characters.
| Value Fuzzy Match Character | Description |
|---|---|
* (asterisk) |
Wildcard, indicating zero to many characters. |
|(pipe) |
OR operand for dimension values. |
Example 1 (Single Value): Basic query for CPU utilization, excluding fault domain 1.
CpuUtilization [1m]{faultDomain != "FAULT-DOMAIN-1"}.mean()Example 2 (Multiple Values): Basic query for CPU utilization, excluding fault domains 1 and 2.
CpuUtilization [1m]{faultDomain !~ "FAULT-DOMAIN-1|FAULT-DOMAIN-2"}.mean()This section describes how to select dimensions on the Metrics Explorer page. For alarm query edits, see Creating a Basic Alarm.
-
To select dimensions by updating the MQL expression, follow these steps:
-
Edit the text in the Query code editor box.
Dimension example in an MQL expression:
CpuUtilization[1m]{faultDomain = "FAULT-DOMAIN-1"}.mean()In this example, the query limits returned data to fault domain 1. The graph from Example Query and Metric Chart now shows four metric streams. Each metric stream corresponds to an instance in fault domain 1.
-
Edit the text in the Query code editor box.
-
To select dimensions by updating the MQL expression, follow these steps:
Use the oci monitoring metric-data summarize-metrics-data command and required parameters to query metric data. Use the
--query-textparameter to select dimensions (part of the MQL expression).oci monitoring metric-data summarize-metrics-data --query-text <mql_expression> [...]For a complete list of parameters and values for CLI commands, see the Command Line Reference for Monitoring.
Run the SummarizeMetricsData operation to query metric data. Use the
queryattribute to select dimensions (part of the MQL expression). For an example, see SummarizeMetricsDataDetails.