Metrics API - Selector transformation
The metric selector is a powerful instrument for specifying which metrics you want to read with the GET metric data points call.
In addition, you can transform the resulting set of data points. These transformations modify the plain metric data.
All functions fall into four categories:
Category | Description |
---|---|
Dimension augmentation | Adds dimensions without merging. |
Dimension mapping | Adds, removes, or changes dimensions. May merge payloads on collision. |
Dimension filtering | Examines dimension values and either keeps or rejects them and their associated data. |
Payload aggregation | Changes how numeric values are calculated for payloads. |
Aggregation transformation
Syntax | :(<agg1>,<agg2>,<aggN>) :(percentile(99.9)) |
Category | Payload aggregation |
Arguments | A list of desired aggregations. |
Specifies the aggregation of the returned data points. If you specify several aggregations, each is returned as a different metric object. The following aggregation types are available:
- avg
- count
- max
- min
- percentile
- sum
- value
The percentile aggregation expects a parameter in range from 0
to 100
. For example, :(percentile(99.9))
gets the 99.9th percentile.
For example, if you query the builtin:host.disk.avail metric with min and max aggregations (selector syntax for that is builtin:host.disk.avail:(min,max))
, the response will contain two separate metric objects—builtin:host.disk.avail:min and builtin:host.disk.avail:max.
Filter transformation
Syntax | :filter(<condition1>,<condition2>,<conditionN>) |
Category | Dimension filtering |
Arguments | A list of filtering conditions. A dimension has to match all of the conditions to pass filtering. |
The filter transformation filters the response by the specified criteria. It enables you to filter the data points by a secondary dimension, as scope supports only the first dimension, which is an entity. The combination of scope and filter transformation helps you maximize data filtering efficiency.
Conditions
The :filter
transformation supports the following conditions.
Syntax | Description |
---|---|
prefix(<dimension>,<expected prefix>) |
Matches if the value of the specified dimension starts with the specified prefix. |
suffix(<dimension>,<expected suffix>) |
Matches if the value of the specified dimension ends with the specified suffix. |
contains(<dimension>, <expected value>) |
Matches if the value of the specified dimension contains the specified value. |
eq(<dimension>,<expected value>) |
Matches if the value of the specified dimension equals the specified value. |
ne(<dimension>,Inverted Exact Match) |
The reverse of the eq condition. The dimension with the specified name is excluded from the response. |
remainder() |
The response contains only the remainder dimension. DESK keeps only the top X dimensions (the exact number depends on the metric, aggregation, timeframe, and other factors). All other dimensions are aggregated into one, called the remainder dimension. |
Condition combinations
Each condition can be a combination of subconditions.
Syntax | Description |
---|---|
and(<subcondition1>,<subcondition2>,<subconditionN>) |
All subconditions must be fulfilled. |
or(<subcondition1>,<subcondition2>,<subconditionN>) |
At least one subcondition must be fulfilled. |
not(<subcondition>) |
Reverses the subcondition. For example, it turns contains into does not contain. |
Fold transformation
Syntax | :fold |
Category | Payload aggregation |
Arguments | None |
The fold transformation aggregates a data points list into an aggregated data point—the result for the transformed metric contains a values array instead of a series array.
It has the same effect as setting the resolution parameter to Inf
. However, with the fold transformation you can query a metric as a list of data points and an aggregated data point within one query.
Merge transformation
Syntax | :merge(<dimension0>,<dimension1>,<dimnesionN>) |
Category | Dimension mapping |
Arguments | A list of dimensions to be removed. |
The merge transformation removes the specified dimensions from the result. All series/values that have the same dimensions after the removal are merged into one. The values are recalculated according to the selected aggregation.
{
"metrics": {
"builtin:synthetic.browser.event.actionDuration.load.geo:(count)": {
"series": [
{
"dimensions": [
"SYNTHETIC_TEST_STEP-002D5D5A0230A18F",
"GEOLOCATION-B69A5A40388CC698"
],
"values": [
{
"timestamp": 1559865600000,
"value": 143
},
{
"timestamp": 1560124800000,
"value": 156
},
{
"timestamp": 1560384000000,
"value": 217
}
]
},
{
"dimensions": [
"SYNTHETIC_TEST_STEP-002D5D5A0230A18F",
"GEOLOCATION-43BA84CAB24D7950"
],
"values": [
{
"timestamp": 1559865600000,
"value": 773
},
{
"timestamp": 1560124800000,
"value": 804
},
{
"timestamp": 1560384000000,
"value": 801
},
]
}
]
}
}
}
{
"metrics": {
"builtin:synthetic.browser.event.actionDuration.load.geo:(count):merge(1)": {
"series": [
{
"dimensions": [
"SYNTHETIC_TEST_STEP-002D5D5A0230A18F"
],
"values": [
{
"timestamp": 1559865600000,
"value": 916
},
{
"timestamp": 1560124800000,
"value": 960
},
{
"timestamp": 1560384000000,
"value": 1018
}
]
}
]
}
}
}
Names transformation
Syntax | :names |
Category | Dimension augmentation. |
Arguments | None |
The names transformation adds the name of the dimension to the dimensions array of the response. The name of each dimension is placed before the ID of the dimension.
"dimensions": [
"HOST-D4EC0D8F510A6F60",
"DISK-6FE914EBA40DACD4"
]
"dimensions": [
"l-009",
"HOST-D4EC0D8F510A6F60",
"C:\\",
"DISK-6FE914EBA40DACD4"
]
Parents transformation
Syntax | :parents |
Category | Dimension augmentation. |
Arguments | None |
The parents transformation adds the parent of the dimension to the dimensions array of the response. The parent of each dimension is placed before the dimension itself.
This transformation works only if the dimension entity is part of another, bigger entity. For example, PROCESS_GROUP_INSTANCE
is always the child of the HOST
it runs on. The following relationships are supported.
Child dimension | Parent dimension |
---|---|
SERVICE_METHOD | SERVICE |
APPLICATION_METHOD | APPLICATION |
PROCESS_GROUP_INSTANCE | HOST |
DISK | HOST |
SYNTHETIC_TEST_STEP | SYNTHETIC_TEST |
"dimensions": [
"PROCESS_GROUP_INSTANCE-FC43333762E05451"
]
"dimensions": [
"HOST-D4EC0D8F510A6F60",
"PROCESS_GROUP_INSTANCE-FC43333762E05451"
]
Combining transformations
You can combine any number of transformations as long as the total length of the selector string is within the limit (see Limitations below). The selector string is evaluated from left to right. Each successive transformation is applied to the result of the previous transformation.
For example, consider builtin:apps.other.apdex.geo
, which includes geolocations. We may know the name of the desired geolocation (for example, Austria) but not the ID of the geolocation. We want to use this name for filtering. This can be achieved by combining the :names
and :filter
transformations:
builtin:apps.other.apdex.geo:names:filter(eq(GEOLOCATION_DIMENSION_name,Austria))
Dimensions
Many of DESK metrics may be fine-grained with dimensions. For example, the builtin:host.disk.avail
metric has two dimensions:
- The primary dimension is
Host
. - The secondary dimension is
Disk
Wherever you see the <dimension>
or <dimensionX>
placeholders in the example syntax, you can select a specific dimensions of the metric. You can reference a dimension in two ways:
- By dimension name. For
builtin:host.disk.avail
these areHost
andDisk
. - By 0-based index of the dimension. In
builtin:host.disk.avail
metric these are0
forHost
and1
Disk
.
Query a metric with the GET metric descriptors call to obtain information about available dimensions and their indexes.
Transform operations modify the list of dimensions, by adding/removing them. Subsequent transformations operate with modified list of dimensions, therefore names and indexes may be different from the original. Query the metric descriptor with preceding transformations (for example builtin:host.disk.avail:names
) to view the new list of available dimensions and their indexes.
Limitations
The total length of the selector string is limited to 1,000 characters.
You can select up to 10 metrics in one query.