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.

Limitations

The total length of the selector string is limited to 1,000 characters.

You can select up to 10 metrics in one query.

Dimensions

Many Dynatrace metrics can be referenced with finer granularity using 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 dimension of the metric. You can reference a dimension by its name. For builtin:host.disk.avail these are Host and Disk.

Query a metric with the GET metric descriptors call to obtain information about available dimensions.

Transform operations modify the list of dimensions by adding/removing them. Subsequent transformations operate on modified list of dimensions, therefore names 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.

Aggregation transformation

Syntax :(<agg1>,<agg2>,<aggN>)
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:

Aggregation Notes
min Selects the lowest value from the time slot. All null values are ignored.
max Selects the highest value from the time slot. All null values are ignored.
avg Calculates the arithmetic mean of all values from the time slot. All null values are ignored.
sum Sums up all values from the time slot. All null values are ignored.
value Takes a single value as is. Only applicable to previously aggregated values.
count Takes the count of the values in the time slot. All null values are ignored.
percentile(N) Calculates the Nth percentile, with N the 0 to 100 range.

Syntax examples

:(percentile(99.9)) Gets the 99.9th percentile.
(min,max) Gets a metric with min and max aggregations as two separate metric objects.

For example, for the builtin:host.disk.avail metric these will be 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 entitySelector 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.
eq(<dimension>,<expected value>) Matches if the value of the specified dimension equals the specified value.
ne(<dimension>,<value to be excluded>) 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.

Dynatrace 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.

In every condition, you can specify a dimension by name or by index.

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.

Syntax examples

:filter(or(eq(Host,HOST-0990886B7D39FE29),eq(Host,HOST-0956C3557E9109C1))) Filters data points to those delivered by either HOST-0990886B7D39FE29 or HOST-0990886B7D39FE29 hosts.
:filter(and(prefix(App Version,2.),ne(Operating system,OS-472A4A3B41095B09))) Filters data point to those delivered by an application of major version 2 that is not run on the OS-472A4A3B41095B09 operating system.

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>,<dimensionN>)
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.

{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:synthetic.browser.event.actionDuration.load.geo:(count)",
      "data": [
        {
          "dimensions": [
            "SYNTHETIC_TEST_STEP-002D5D5A0230A18F",
            "GEOLOCATION-B69A5A40388CC698"
          ],
          "timestamps": [
            1559865600000,
            1560124800000,
            1560384000000
          ],
          "values": [
            143,
            156,
            217
          ]
        },
        {
          "dimensions": [
            "SYNTHETIC_TEST_STEP-002D5D5A0230A18F",
            "GEOLOCATION-43BA84CAB24D7950"
          ],
          "timestamps": [
            1559865600000,
            1560124800000,
            1560384000000
          ],
          "values": [
            773,
            804,
            801
          ]
        }
      ]
    }
  ]
}

Names transformation

Syntax :names
Category Dimension augmentation.
Arguments None

The names transformation adds the name of the dimension value 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"
]

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"
]

Rate transformation

Syntax :rate(5m)
Arguments m: per minute
h: per hour
d: per day
w: per week
M: per month
y: per year

The rate transformation converts a count-based metric (for example, bytes) into a rate-based metric (for example, bytes per minute).

Any argument can be modified by an integer factor. For example, 5m stands for per 5 minutes rate. If no argument is specified, the per 1 minute rate is used.

You can use the rate transformation on values with a VALUE, SUM, or COUNT aggregation, regardless of whether it is a built-in aggregation or a result of an aggregation transformation.

You can use rate transformation only once in a single transformation chain.

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))