Metrics API - Metric selector

The metric selector is a powerful instrument for specifying which metrics you want to read with the GET metric data points or the GET metrics call.

In addition, you can transform the resulting set of data points. These transformations modify the plain metric data.

Limitations

The selector must contain at least one metric key.
The total length of the metricSelector string is limited to 5,000 characters.
You can query data points of up to 10 metrics in one query.

Select metrics

You need to specify a metric key to select it. You can specify multiple metric keys separated by commas (for example, metrickey1,metrickey2). To select multiple metrics belonging to the same parent, list the last part of the required metric keys in parentheses, separated by commas. For example, to list the builtin:host.cpu.idle and builtin:host.cpu.user metric, write: builtin:host.cpu.(idle,user).

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

Query a metric with the GET metric descriptor call to obtain information about available dimensions—you can find them in the dimensionDefinitions field of the metric descriptor.

Show descriptor example

json
{
  "dimensionDefinitions": [
    {
      "key": "dt.entity.host",
      "name": "Host",
      "displayName": "Host",
      "index": 0,
      "type": "ENTITY"
    },
    {
      "key": "dt.entity.disk",
      "name": "Disk",
      "displayName": "Disk",
      "index": 1,
      "type": "ENTITY"
    }
  ]
}

Wherever you see the <dimension> placeholder in the example syntax, you can select a specific dimension of the metric. You can reference a dimension by its key. For example, for builtin:host.disk.avail these are dt.entity.host and dt.entity.disk.

Transform operations modify the list of dimensions by adding or removing them. Subsequent transformations operate on modified list of dimensions. Query the metric descriptor with preceding transformations (for example builtin:host.disk.avail:names) to view the new list of available dimensions.

Remainder dimension

Dynatrace keeps only the top X dimension tuples (the exact number depends on the metric, aggregation, timeframe, and other factors). All other dimension tuples are aggregated into one, called the remainder dimension.

If the query result includes this dimension, the dimensions and dimensionMap value will be null. However, if the dimensionMap does not contain an entry at all, then this is not the remainder dimension, but rather a literal null value.

Aggregation transformation


Syntax	`:(<agg1>,<agg2>,<aggN>)`
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. Each of these objects is contributing to the limit of metrics per query.

The following aggregation types are available:

Aggregation	Notes
auto	Applies the default aggregation. To check the default aggregation, query a metric with the GET metric descriptors call and check the defaultAggregation field.
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 all values from the time slot. All `null` values are ignored.
value	Takes a single value as is. Only applicable to previously aggregated values and metrics that support the `value` aggregation.
count	Takes the count of the values in the time slot. All `null` values are ignored.
percentile(`N`)	Calculates the N^th percentile, where N is between `0` and `100` (inclusive).

Syntax examples

plaintext
:(percentile(99.9))

Gets the 99.9^th percentile.

plaintext
:(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.

Default transformation


Syntax	`:default(0)`
Arguments	The value to replace `null` values in the result.

The default transformation replaces null values in the payload with the specified value.

Show example

Before default transformationAfter default transformation

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:tech.jvm.memory.pool.collectionCount",
      "data": [
        {
          "dimensions": [
            "PROCESS_GROUP_INSTANCE-A02ED607B5E9DD20",
            "30382",
            "G1 Old Gen",
            "G1 Old Generation"
          ],
          "dimensionMap": {
            "poolname": "G1 Old Gen",
            "rx_pid": "30382",
            "gcname": "G1 Old Generation",
            "dt.entity.process_group_instance": "PROCESS_GROUP_INSTANCE-A02ED607B5E9DD20"
          },
          "timestamps": [1623585600000, 1623628800000, 1623672000000, 1623715200000],
          "values": [3, null, null, 1]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:tech.jvm.memory.pool.collectionCount",
      "data": [
        {
          "dimensions": [
            "PROCESS_GROUP_INSTANCE-A02ED607B5E9DD20",
            "30382",
            "G1 Old Gen",
            "G1 Old Generation"
          ],
          "dimensionMap": {
            "poolname": "G1 Old Gen",
            "rx_pid": "30382",
            "gcname": "G1 Old Generation",
            "dt.entity.process_group_instance": "PROCESS_GROUP_INSTANCE-A02ED607B5E9DD20"
          },
          "timestamps": [1623585600000, 1623628800000, 1623672000000, 1623715200000],
          "values": [3, 0, 0, 1]
        }
      ]
    }
  ]
}

Delta transformation


Syntax	`:delta`
Arguments	None

The delta transformation replaces each data point with the difference from the previous data point (0 if the difference is negative). The first data point of the original set is omitted from the result.

You must apply an aggregation transformation before using the delta transformation.

Show example

Before delta transformationAfter delta transformation

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:service.keyRequest.count.server:value",
      "data": [
        {
          "dimensions": ["SERVICE_METHOD-BD61DD6DAC1EFDE1"],
          "dimensionMap": {
            "dt.entity.service_method": "SERVICE_METHOD-BD61DD6DAC1EFDE1"
          },
          "timestamps": [1630886400000, 1630929600000, 1630972800000, 1631016000000, 1631059200000],
          "values": [8338, 8449, 8343, 8372, 8425]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:service.keyRequest.count.server:value:delta",
      "data": [
        {
          "dimensions": ["SERVICE_METHOD-BD61DD6DAC1EFDE1"],
          "dimensionMap": {
            "dt.entity.service_method": "SERVICE_METHOD-BD61DD6DAC1EFDE1"
          },
          "timestamps": [1630886400000, 1630929600000, 1630972800000, 1631016000000, 1631059200000],
          "values": [null, 111, 0, 29, 53]
        }
      ]
    }
  ]
}

Filter transformation


Syntax	`:filter(<condition1>,<condition2>,<conditionN>)`
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 expected prefix.
`eq("<dimension>","<expected value>")`	Matches if the value of the specified dimension equals the expected value.
`ne("<dimension>","<value to be excluded>")`	The reverse of the `eq` condition. The dimension with the specified name is excluded from the response.
`in("<dimension>",entitySelector("<selector>")`	Matches if the value of the specified dimension equals any of the expected values provided by the entity selector.
`existsKey("<dimension>")`	Matches if the specified dimension exists.
`remainder("<dimension>")`	Matches if the specified dimension is part of the remainder.
`series(<aggregation>,<operator>(<reference value>))`	The response contains only series with data points matching the provided criterion.

Quotes (") and tildes (~) that are part of the dimension key or dimension value (including entity selector syntax) must be escaped with a tilde (~).

Series condition

The series condition filters the time-aggregated value of the data points for a series by the provided criterion. That is, the specified aggregation is applied and then this single value result is compared to the reference value using the specified operator. For example, for series(avg, gt(10)), firstly the average over all data points of the series is calculated and, then, this value is checked to be greater than 10. If a series does not match this criterion, it is removed from the provided result. That is, the series operator cannot be used to filter individual data points of a series.

The condition supports the following aggregations and operators.

Available aggregations

min
max
avg
sum
median
percentile(N), with N in the 0 to 100 range.

Available operators

lt: lower than
le: lower than or equal to
eq: equal
ne: not equal
gt: greater than
ge: greater than or equal to

Compound condition

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

plaintext
:filter(or(eq("dt.entity.host.name","Server ~"North~""),eq("dt.entity.host.name","Server ~"West~"")))

Filters data points to those delivered by either Server "North" or Server "West".

plaintext
:filter(and(prefix("App Version","2."),ne("dt.entity.os","OS-472A4A3B41095B09")))

Filters data points to those delivered by an application of major version 2 that is not run on the OS-472A4A3B41095B09 operating system.

Fold transformation


Syntax	`:fold(<aggregation>)`
Arguments	optional Dynatrace 1.232+ The required aggregation method.

The fold transformation combines a data points list into a single data point. To get the result in a specific aggregation, specify the aggregation as an argument. If the specified aggregation is not supported, the default aggregation is used. For example, :fold(median) on a gauge metric equals to :fold(avg) because median is not supported and avg is the default. If an aggregation has been applied in the transformation chain before, the argument is ignored.

Show example

Before fold transformationAfter fold transformation

json
{
  "metricId": "builtin:host.disk.avail",
  "data": [
    {
      "dimensions": ["HOST-BB4DF8969CB41C60", "DISK-FB78447211EE76BF"],
      "dimensionMap": {
        "dt.entity.disk": "DISK-FB78447211EE76BF",
        "dt.entity.host": "HOST-BB4DF8969CB41C60"
      },
      "timestamps": [1612794060000, 1612794120000, 1612794180000],
      "values": [4.605786630826667e11, 4.424691002026667e11, 439596351488]
    }
  ]
}

json
{
  "metricId": "builtin:host.disk.avail:fold",
  "data": [
    {
      "dimensions": ["HOST-BB4DF8969CB41C60", "DISK-FB78447211EE76BF"],
      "dimensionMap": {
        "dt.entity.disk": "DISK-FB78447211EE76BF",
        "dt.entity.host": "HOST-BB4DF8969CB41C60"
      },
      "timestamps": [1612794480000],
      "values": [4.577198298453333e11]
    }
  ]
}

Last transformation


Syntax	`:last<aggregation>` `:lastReal<aggregation>`
Arguments	optional Dynatrace 1.232+ The required aggregation method.

The last transformation returns the most recent data point from the query timeframe. To get the result in a specific aggregation, specify the aggregation as an argument. If the specified aggregation is not supported, the default aggregation is used. For example, :last(median) on a gauge metric equals to :last(avg) because median is not supported and avg is the default. If an aggregation has been applied in the transformation chain before, the argument is ignored.

If the metric before transformation contains multiple tuples (unique combinations of metric—dimension—dimension value), the most recent timestamp is applied for all tuples. To obtain the actual last timestamp, use the lastReal operator.

Show example

Before last transformationAfter last transformation

json
{
  "totalCount": 3,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\")",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [
            1617178800000, 1617180000000, 1617181200000, 1617182400000, 1617183600000, 1617184800000
          ],
          "values": [90, 106, 110, 96, 116, 102]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [
            1617178800000, 1617180000000, 1617181200000, 1617182400000, 1617183600000, 1617184800000
          ],
          "values": [176, 168, 178, 174, 183, 172]
        },
        {
          "dimensions": ["Germany"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Germany"
          },
          "timestamps": [
            1617178800000, 1617180000000, 1617181200000, 1617182400000, 1617183600000, 1617184800000
          ],
          "values": [1168, 1121, 1154, 1160, 1108, 1135]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 3,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\"):last",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1617184800000],
          "values": [102]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1617184800000],
          "values": [172]
        },
        {
          "dimensions": ["Germany"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Germany"
          },
          "timestamps": [1617184800000],
          "values": [1135]
        }
      ]
    }
  ]
}

Limit transformation


Syntax	`:limit(3)`
Arguments	The maximum number of tuples in the result.

The limit transformation limits the number of tuples (unique combinations of metric—dimension—dimension value) in the response. Only the first X tuples are included in the response; the rest are discarded.

To ensure that the required tuples are at the top of the result, apply the sort transformation before using the limit.

Show example

Before limit transformationAfter limit transformation

json
{
  "totalCount": 4,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\"):sort(value(sum,descending))",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1613559180000],
          "values": [6593]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1613559180000],
          "values": [1002]
        },
        {
          "dimensions": ["Germany"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Germany"
          },
          "timestamps": [1613559180000],
          "values": [564]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 2,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\"):sort(value(sum,descending)):limit(2)",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1613559180000],
          "values": [6593]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1613559180000],
          "values": [1002]
        }
      ]
    }
  ]
}

Merge transformation


Syntax	`:merge("<dimension0>","<dimension1>","<dimensionN>")`
Arguments	A list of dimensions to be removed. A dimension must be specified by its key. Quotes (`"`) and tildes (`~`) that are part of the dimension key must be escaped with a tilde (`~`).

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.

You can apply any aggregation to the result of the merge transformation, including those that the original metric doesn't support.

Show example

Before merge transformationAfter merge transformation

json
{
  "totalCount": 2,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:synthetic.browser.event.actionDuration.load.geo:count",
      "data": [
        {
          "dimensions": ["SYNTHETIC_TEST_STEP-002D5D5A0230A18F", "GEOLOCATION-B69A5A40388CC698"],
          "dimensionMap": {
            "dt.entity.synthetic_test_step": "SYNTHETIC_TEST_STEP-97EF148D63564F29",
            "dt.entity.geolocation": "GEOLOCATION-0A41430434C388A9"
          },
          "timestamps": [1559865600000, 1560124800000, 1560384000000],
          "values": [143, 156, 217]
        },
        {
          "dimensions": ["SYNTHETIC_TEST_STEP-002D5D5A0230A18F", "GEOLOCATION-43BA84CAB24D7950"],
          "timestamps": [1559865600000, 1560124800000, 1560384000000],
          "values": [773, 804, 801]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:synthetic.browser.event.actionDuration.load.geo:count:merge(\"dt.entity.geolocation\")",
      "data": [
        {
          "dimensions": ["SYNTHETIC_TEST_STEP-002D5D5A0230A18F"],
          "dimensionMap": {
            "dt.entity.synthetic_test_step": "SYNTHETIC_TEST_STEP-09D1E2CC97B5878B"
          },
          "timestamps": [1559865600000, 1560124800000, 1560384000000],
          "values": [916, 960, 1018]
        }
      ]
    }
  ]
}

Names transformation


Syntax	`:names`
Arguments	None
Limitations	Applies only to dimensions of the entity type.

The names transformation adds the name of the dimension value to the dimensions array and dimensionMap object of the response. The name of each dimension is placed before the ID of the dimension.

Show example

Before names transformationAfter names transformation

json
{
  "dimensions": ["HOST-BB4DF8969CB41C60", "DISK-FB78447211EE76BF"],
  "dimensionMap": {
    "dt.entity.disk": "DISK-FB78447211EE76BF",
    "dt.entity.host": "HOST-BB4DF8969CB41C60"
  }
}

json
{
  "dimensions": ["l-009", "HOST-BB4DF8969CB41C60", "C:\\", "DISK-FB78447211EE76BF"],
  "dimensionMap": {
    "dt.entity.disk.name": "C:\\",
    "dt.entity.disk": "DISK-FB78447211EE76BF",
    "dt.entity.host.name": "l-009",
    "dt.entity.host": "HOST-BB4DF8969CB41C60"
  }
}

Parents transformation


Syntax	`:parents`
Arguments	None
Limitations	Applies only to dimensions of the entity type listed below.

The parents transformation adds the parent of the dimension to the dimensions array and dimensionMap object 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
SERVICE_INSTANCE	SERVICE
APPLICATION_METHOD	APPLICATION
PROCESS_GROUP_INSTANCE	HOST
DISK	HOST
NETWORK_INTERFACE	HOST
SYNTHETIC_TEST_STEP	SYNTHETIC_TEST
HTTP_CHECK_STEP	HTTP_CHECK
EXTERNAL_SYNTHETIC_TEST_STEP	EXTERNAL_SYNTHETIC_TEST

Show example

Before parents transformationAfter parents transformation

json
{
  "dimensions": ["SERVICE_METHOD-D9D3A16FA577BF1C"],
  "dimensionMap": {
    "dt.entity.service": "SERVICE-C22F1E8EA66FF4C5"
  }
}

json
{
  "dimensions": ["SERVICE-C22F1E8EA66FF4C5", "SERVICE_METHOD-D9D3A16FA577BF1C"],
  "dimensionMap": {
    "dt.entity.service_method": "SERVICE_METHOD-D9D3A16FA577BF1C",
    "dt.entity.service": "SERVICE-C22F1E8EA66FF4C5"
  }
}

Partition transformation

Syntax	`:partition("<partition dimension key>",<partition1>,<partitionN>)`
Arguments	The key of the partition dimension. This is not an existing dimension, but a new one that the transformation will create. Quotes (`"`) and tildes (`~`) that are part of the dimension key must be escaped with a tilde (`~`). A list of partitions to be applied. To learn how to specify them, see the Partition syntax section below.
Dynatrace version	1.230+

The partition transformation splits data points of a series based on the specified criteria. It introduces a new dimension (the partition dimension), with the value determined by a partition criterion. Data points from the original series are distributed between one or several new series according to partition criteria. In each new series, data points that don't pass the criterion or are already taken by another criterion are replaced with null.

You must apply an aggregation transformation before using the partition transformation.

Partition syntax

A single transformation can contain several partitions. These are evaluated from top to bottom; the first matching partition applies.

Each partition must contain a value for the partition dimension that will mark the passed data points and a criterion by which to filter data points.

plaintext
value("partition dimension value",<criterion>)

The following criteria are available:


`lt(X)`	less than X
`le(X)`	less than or equal to X
`eq(X)`	equal to X
`ne(X)`	not equal to X
`ge(X)`	greater than or equal to X
`gt(X)`	greater than X
`range(X,Y)`	greater than or equal to X and less than Y
`otherwise`	A universal operator matching all values. Use it at the end of partition chain as the default case.
`or(<criterion1>,<criterionN>)`	at least one sub-criterion must be fulfilled
`and(<criterion1>,<criterionN>)`	all sub-criteria must be fulfilled
`not(<criterion>)`	Negated criterion matching all values that do not fulfill the criterion.

Show example

The following partition transformation is used in this example:

plaintext
:partition(
    "Action duration",
    value("slow",gt(200)),
    value("fast",lt(100)),
    value("normal",otherwise)
)

It adds the Action duration dimension to the metric and splits data points into three categories based on it:

fast for actions faster than 100 milliseconds.
slow for actions slower than 200 milliseconds.
normal for all other actions.

Before partition transformationAfter partition transformation

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "resolution": "10m",
  "result": [
    {
      "metricId": "builtin:apps.web.action.domInteractive.load.browser:avg",
      "data": [
        {
          "dimensions": ["APPLICATION_METHOD-E418A4BC1DC2C911", "BROWSER-EFB8A292CB368A8D"],
          "dimensionMap": {
            "dt.entity.browser": "BROWSER-EFB8A292CB368A8D",
            "dt.entity.application_method": "APPLICATION_METHOD-E418A4BC1DC2C911"
          },
          "timestamps": [
            1637152200000, 1637152800000, 1637153400000, 1637154000000, 1637154600000,
            1637155200000, 1637155800000, 1637156400000, 1637157000000, 1637157600000,
            1637158200000, 1637158800000, 1637159400000
          ],
          "values": [155, 215, 247, 118, 94, 119, 67, 159, 114, 169, 113, 75, 160]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 3,
  "nextPageKey": null,
  "resolution": "10m",
  "result": [
    {
      "metricId": "builtin:apps.web.action.domInteractive.load.browser:avg:partition(\"Action duration\",value(slow,gt(200)),value(fast,lt(100)),value(normal,otherwise))",
      "data": [
        {
          "dimensions": [
            "BROWSER-EFB8A292CB368A8D",
            "APPLICATION_METHOD-E418A4BC1DC2C911",
            "normal"
          ],
          "dimensionMap": {
            "dt.entity.browser": "BROWSER-EFB8A292CB368A8D",
            "dt.entity.application_method": "APPLICATION_METHOD-E418A4BC1DC2C911",
            "Action duration": "normal"
          },
          "timestamps": [
            1637152200000, 1637152800000, 1637153400000, 1637154000000, 1637154600000,
            1637155200000, 1637155800000, 1637156400000, 1637157000000, 1637157600000,
            1637158200000, 1637158800000, 1637159400000
          ],
          "values": [155, null, null, 118, null, 119, null, 159, 114, 169, 113, null, 160]
        },
        {
          "dimensions": ["BROWSER-EFB8A292CB368A8D", "APPLICATION_METHOD-E418A4BC1DC2C911", "fast"],
          "dimensionMap": {
            "dt.entity.browser": "BROWSER-EFB8A292CB368A8D",
            "dt.entity.application_method": "APPLICATION_METHOD-E418A4BC1DC2C911",
            "Action duration": "fast"
          },
          "timestamps": [
            1637154000000, 1637154600000, 1637155200000, 1637155800000, 1637156400000,
            1637157000000, 1637157600000, 1637158200000, 1637158800000, 1637159400000,
            1637160000000, 1637160600000, 1637161200000
          ],
          "values": [null, null, null, null, 94, null, 67, null, null, null, null, 75, null]
        },
        {
          "dimensions": ["BROWSER-EFB8A292CB368A8D", "APPLICATION_METHOD-E418A4BC1DC2C911", "slow"],
          "dimensionMap": {
            "dt.entity.browser": "BROWSER-EFB8A292CB368A8D",
            "dt.entity.application_method": "APPLICATION_METHOD-E418A4BC1DC2C911",
            "Action duration": "slow"
          },
          "timestamps": [
            1637154000000, 1637154600000, 1637155200000, 1637155800000, 1637156400000,
            1637157000000, 1637157600000, 1637158200000, 1637158800000, 1637159400000,
            1637160000000, 1637160600000, 1637161200000
          ],
          "values": [null, 215, 247, null, null, null, null, null, null, null, null, null, null]
        }
      ]
    }
  ]
}

Rate transformation

Syntax

:rate(5m)

Arguments

The base of the rate. The following values are supported:

s: per second
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 means per 5 minutes rate. If no argument is specified, the per 1 minute rate is used.

You can use the rate transformation with any metric that supports the VALUE aggregation. Query a metric with the GET metric descriptors call to obtain information about available aggregations. If the metric doesn't support the VALUE aggregation, apply the aggregation transformation first and then the rate transformation.

You must apply an aggregation transformation before using the rate transformation.
You can use the rate transformation only once in a single transformation chain.

Rollup transformation

Syntax	`:rollup(avg,15m)`
Arguments	The required aggregation of the rollup. Supported aggregations are: `min` `max` `avg` `sum` `median` `percentile(N)`, with N in the `0` to `100` range. The duration of the rollup window in minutes. The duration must be a multiple of the query resolution. For example, if the resolution is five minutes, the rollup can be `5m`, `10m`, `15m`, and so on.
Dynatrace version	1.230+

The rollup transformation smoothes data points, removing any spikes from the requested timeframe.

The transformation takes each data point from the query timeframe, forms a rollup window by looking into past data points (so the initial data point becomes the last point of the window), calculates the requested aggregation of all original values, and then replaces each data point in the window with the result of the calculation.

For example, if you specify :rollup(avg,5m) and the resolution of the query is one minute, the transformation takes a data point, adds the four previous data point to form a rollup window, and then uses the average of these five datapoints to calculate the final datapoint value.

Limitations

You must apply an aggregation transformation before using the rollup transformation.
The rollup window duration is limited to 60 minutes.
You can roll up data from the last 2 weeks (including rollup windows) only. That is, the oldest data point of your query can't be more than 2w-windowDuration in the past.

Show example

Before rollup transformationAfter rollup transformation

Rollup transformation - before

Rollup transformation - after

Smooth transformation


Syntax	`:smooth(skipfirst)`
Arguments	The smoothing strategy. Only the `skipfirst` strategy is supported.

The smooth transformation smooths a series of data points after a data gap (one or several data points with the value of null).

The skipfirst strategy replaces the first data point after the data gap with null.

Show example

Before smooth transformationAfter smooth transformation

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:service.keyRequest.count.server",
      "data": [
        {
          "dimensions": ["SERVICE_METHOD-BBA9C77B774B0C15"],
          "dimensionMap": {
            "dt.entity.service_method": "SERVICE_METHOD-BBA9C77B774B0C15"
          },
          "timestamps": [
            1628618460000, 1628618520000, 1628618580000, 1628618640000, 1628618700000,
            1628618760000, 1628618820000, 1628618880000, 1628618940000, 1628619000000
          ],
          "values": [null, 15, 13, 15, null, null, 28, 14, 14, 13]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 1,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:service.keyRequest.count.server:smooth(skipfirst)",
      "data": [
        {
          "dimensions": ["SERVICE_METHOD-BBA9C77B774B0C15"],
          "dimensionMap": {
            "dt.entity.service_method": "SERVICE_METHOD-BBA9C77B774B0C15"
          },
          "timestamps": [
            1628618460000, 1628618520000, 1628618580000, 1628618640000, 1628618700000,
            1628618760000, 1628618820000, 1628618880000, 1628618940000, 1628619000000
          ],
          "values": [null, null, 13, 15, null, null, null, 14, 14, 13]
        }
      ]
    }
  ]
}

Sort transformation


Syntax	`:sort(<sorting key 1>,<sorting key 2>)`
Arguments	One or several sorting keys.

The sort transformation specifies the order of tuples (unique combinations of metric—dimension—dimension value) in the response. You can specify one or several sorting criteria. The first criterion is used for sorting. Further criteria are used for tie-breaking. You can choose the direction of the sort:

ascending
descending

Dimension sorting

To sort results by the value of a dimension, use the dimension("<dimension>",<direction>) key. Quotes (") and tildes (~) that are part of the dimension key must be escaped with a tilde (~).

Entity dimensions are sorted lexicographically (0..9a..z) by Dynatrace entity ID values.

String dimensions are sorted lexicographically.

Data points sorting

To sort results by metric data points in a dimension, use the value(<aggregation>,<direction>) key.

The following aggregations are available:

min
max
avg
sum
median
percentile(N), with N in the 0 to 100 range.

The aggregation is used only for sorting and doesn't affect the returned data points.

The sorting is applied to the resulting data points of the whole transformation chain before the sort transformation. If the transformation chain doesn't have an aggregation transformation, the sorting is applied to the default aggregation of the metric.

Show example

Before sort transformationAfter sort transformation

json
{
  "totalCount": 4,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\")",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1613557980000],
          "values": [6543]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1613557980000],
          "values": [1009]
        },
        {
          "dimensions": ["Germany"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Germany"
          },
          "timestamps": [1613557980000],
          "values": [6673]
        },
        {
          "dimensions": ["Lichtenstein"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Lichtenstein"
          },
          "timestamps": [1613557980000],
          "values": [86]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 4,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\"):sort(dimension(\"dt.entity.geolocation.name\",ascending))",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1613557440000],
          "values": [6543]
        },
        {
          "dimensions": ["Germany"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Germany"
          },
          "timestamps": [1613557440000],
          "values": [6673]
        },
        {
          "dimensions": ["Lichtenstein"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Lichtenstein"
          },
          "timestamps": [1613557980000],
          "values": [86]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1613557440000],
          "values": [1009]
        }
      ]
    }
  ]
}

Split by transformation


Syntax	`:splitBy("<dimension0>","<dimension1>","<dimensionN>")`
Arguments	A list of dimensions to be preserved in the result. A dimension must be specified by its key. Quotes (`"`) and tildes (`~`) that are part of the dimension key must be escaped with a tilde (`~`).

The split by transformation keeps the specified dimensions in the result and merges all remaining dimensions. The values are recalculated according to the selected aggregation.

You can apply any aggregation to the result of the split by transformation, including those that the original metric doesn't support.

Show example

Before split by transformationAfter split by transformation

json
{
  "totalCount": 4,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names",
      "data": [
        {
          "dimensions": [
            "easyTravel Demo",
            "MOBILE_APPLICATION-752C288D59734C79",
            "Android",
            "OS-472A4A3B41095B09",
            "Switzerland",
            "GEOLOCATION-976217DC7560B588"
          ],
          "dimensionMap": {
            "dt.entity.device_application.name": "easyTravel Demo",
            "dt.entity.os": "OS-472A4A3B41095B09",
            "dt.entity.os.name": "Android",
            "dt.entity.device_application": "MOBILE_APPLICATION-752C288D59734C79",
            "dt.entity.geolocation.name": "Switzerland",
            "dt.entity.geolocation": "GEOLOCATION-976217DC7560B588"
          },
          "timestamps": [1612950360000],
          "values": [557]
        },
        {
          "dimensions": [
            "easyTravel Demo",
            "MOBILE_APPLICATION-752C288D59734C79",
            "Android",
            "OS-472A4A3B41095B09",
            "Austria",
            "GEOLOCATION-EADFE05E062C8D33"
          ],
          "dimensionMap": {
            "dt.entity.device_application.name": "easyTravel Demo",
            "dt.entity.os": "OS-472A4A3B41095B09",
            "dt.entity.os.name": "Android",
            "dt.entity.device_application": "MOBILE_APPLICATION-752C288D59734C79",
            "dt.entity.geolocation.name": "Austria",
            "dt.entity.geolocation": "GEOLOCATION-EADFE05E062C8D33"
          },
          "timestamps": [1612950360000],
          "values": [328]
        },
        {
          "dimensions": [
            "easyTravel Demo",
            "MOBILE_APPLICATION-752C288D59734C79",
            "iOS",
            "OS-62028BEE737F03D4",
            "Switzerland",
            "GEOLOCATION-976217DC7560B588"
          ],
          "dimensionMap": {
            "dt.entity.device_application.name": "easyTravel Demo",
            "dt.entity.os": "OS-62028BEE737F03D4",
            "dt.entity.os.name": "iOS",
            "dt.entity.device_application": "MOBILE_APPLICATION-752C288D59734C79",
            "dt.entity.geolocation.name": "Switzerland",
            "dt.entity.geolocation": "GEOLOCATION-976217DC7560B588"
          },
          "timestamps": [1612950360000],
          "values": [383]
        },
        {
          "dimensions": [
            "easyTravel Demo",
            "MOBILE_APPLICATION-752C288D59734C79",
            "iOS",
            "OS-62028BEE737F03D4",
            "Austria",
            "GEOLOCATION-EADFE05E062C8D33"
          ],
          "dimensionMap": {
            "dt.entity.device_application.name": "easyTravel Demo",
            "dt.entity.os": "OS-62028BEE737F03D4",
            "dt.entity.os.name": "iOS",
            "dt.entity.device_application": "MOBILE_APPLICATION-752C288D59734C79",
            "dt.entity.geolocation.name": "Austria",
            "dt.entity.geolocation": "GEOLOCATION-EADFE05E062C8D33"
          },
          "timestamps": [1612950360000],
          "values": [214]
        }
      ]
    }
  ]
}

json
{
  "totalCount": 2,
  "nextPageKey": null,
  "result": [
    {
      "metricId": "builtin:apps.other.sessionCount.osAndGeo:names:splitBy(\"dt.entity.geolocation.name\")",
      "data": [
        {
          "dimensions": ["Austria"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Austria"
          },
          "timestamps": [1612950360000],
          "values": [542]
        },
        {
          "dimensions": ["Switzerland"],
          "dimensionMap": {
            "dt.entity.geolocation.name": "Switzerland"
          },
          "timestamps": [1612950360000],
          "values": [940]
        }
      ]
    }
  ]
}

Time shift transformation

Syntax

:timeshift(5m)

Arguments

The period of the shift. The following values are supported:

s: seconds Dynatrace version 1.228+
m: minutes
h: hours
d: days
w: weeks

The time shift transformation shifts the timeframe specified by the from and to query parameters and maps the resulting data points to timestamps from the original timeframe. It can help you hand data from different time zones or put yesterday's and today's data on the same chart for visual comparison.

A positive argument shifts the timeframe into the future; a negative argument shifts the timeframe into the past.

You can use this transformation to handle data from different time zones

Let's consider an example with a timeframe from 1615550400000 (March 12, 2021 13:00 CET) to 1615557600000 (March 12, 2021 15:00 CET) and a time shift of -1d (one day into the past).

The data points will be queried for the timeframe from 1615464000000 (March 11, 2021 13:00 CET) to 1615471200000 (March 11, 2021 15:00 CET).
Timestamps in the response will be aligned to the original timeframe. For example, the data point with a timestamp of 1615465800000 (March 11, 2021 13:30 CET) will be returned as 1615552200000 (March 12, 2021 13:30 CET).

Unit transformations

Set unit


Syntax	`:setUnit(<unit>)`
Arguments	The desired unit. To fetch the list of available units, use the GET all units API call.
Dynatrace version	1.235+

The setUnit transformation sets the unit in the metric metadata.

This transformation does not affect data points.

To unit


Syntax	`:toUnit(<sourceUnit>,<targetUnit>)`
Arguments	The source and the target unit of the transformation. To fetch the list of available units, use the GET all units API call.
Dynatrace version	1.235+

The toUnit transformation converts data points from the source unit to target unit. If specified units are incompatible, the original unit is persisted and a warning is included in the response.

You must apply an aggregation transformation before using the unit transformations.

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 section). 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.osAndGeo, 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:

plaintext
builtin:apps.other.apdex.geo:names:filter(eq(dt.entity.geolocation.name,Austria))