Custom metric metadata

To add more context to data points and their dimensions, your custom metric can carry additional useful information, such as the unit of measurement, display name, and value ranges.

You can provide such information via custom metric metadata. Metadata and data points are stored independently from data points and tied together by the metric key. You can push data points and set metadata in any order.

You cannot provide metadata for built-in or calculated metrics; metadata is supported only for custom ingested metrics.

Available parameters

The following parameters are available for metric metadata.

ParametersExample JSON

Parameter	Type	Description
displayName	string	The name of the metric in the user interface.
description	string	A short description of the metric.
unit	string	The unit of the metric. Find the possible values in the description of the unit field for built-in metrics.
tags	string[]	A list of tags applied to the metric.
metricProperties	MetricProperties	A list of the metric's properties.
dimensions	MetricDimensions[]	A list of the metric's dimensions.

The `MetricProperties` object

Properties of a metric.

Parameter	Type	Description
minValue	integer	The minimum allowed value of the metric.
maxValue	integer	The maximum allowed value of the metric.
rootCauseRelevant	boolean	Whether (`true` or `false`) the metric is related to a root cause of a problem. A root-cause relevant metric represents a strong indicator for a faulty component.
impactRelevant	boolean	Whether (`true` or `false`) the metric is relevant to a problem's impact. An impact-relevant metric is highly dependent on other metrics and changes because an underlying root-cause metric has changed.
valueType	string	The type of the metric's value. You have these options: `score`: A score metric is a metric where high values indicate a good situation, while low values indicate trouble. An example of such a metric is a success rate. `error`: An error metric is a metric where high values indicate trouble, while low values indicate a good situation. An example of such a metric is an error count.
latency	integer	The reporting delay of the metrics, in minutes. The delay caused by constraints of cloud vendors or other third-party data sources that leads to a latency in data ingest on the Dynatrace side.

The `MetricDimensions` object

A dimension of the metric.

Parameter	Type	Description
key	string	The key of the dimension to be used in the ingestion protocol.
displayName	string	The name of the dimension in the user interface.

json
{
  "displayName": "Total revenue",
  "description": "Total store revenue by region, city, and store",
  "unit": "Unspecified",
  "tags": ["KPI", "Business"],
  "metricProperties": {
    "maxValue": 1000000,
    "minValue": 0,
    "rootCauseRelevant": false,
    "impactRelevant": true,
    "valueType": "score",
    "latency": 1
  },
  "dimensions": [
    {
      "key": "city",
      "displayName": "City name"
    },
    {
      "key": "country",
      "displayName": "Country name"
    },
    {
      "key": "region",
      "displayName": "Sales region"
    },
    {
      "key": "store",
      "displayName": "Store #"
    }
  ]
}

Set metric metadata

Use the POST an object call of the Settings API to provide metadata for your metric. Use the following parameters in the payload:

Field	Value
scope	metric-{your-metric-key}
schemaId	builtin:metric.metadata
value	The desired set of metadata. See the available fields above.

Example payload

json
[
  {
    "scope": "metric-business.shop.revenue",
    "schemaId": "builtin:metric.metadata",
    "value": {
      "displayName": "Total revenue",
      "description": "Total store revenue by region, city, and store",
      "unit": "Unspecified",
      "tags": ["KPI", "Business"],
      "metricProperties": {
        "maxValue": 1000000,
        "minValue": 0,
        "rootCauseRelevant": false,
        "impactRelevant": true,
        "valueType": "score",
        "latency": 1
      },
      "dimensions": [
        {
          "key": "city",
          "displayName": "City name"
        },
        {
          "key": "country",
          "displayName": "Country name"
        },
        {
          "key": "region",
          "displayName": "Sales region"
        },
        {
          "key": "store",
          "displayName": "Store #"
        }
      ]
    }
  }
]

Alternatively, you can:

Send metadata via the ingestion protocol.
Configure a metric's metadata in Metrics browser.

View metric metadata

You can retrieve the metadata of a metric via the GET metric descriptor call of the Metrics v2 API or via the Metrics browser.

Custom metric metadata

Available parameters

The MetricProperties object

The MetricDimensions object

Set metric metadata

View metric metadata

The `MetricProperties` object

The `MetricDimensions` object