• Home
  • API
  • Basics
  • Migration guides for deprecated APIs
  • Metric events to Settings

Migrate from Metric events API to Settings API

Anomaly detection API - Metric events has been deprecated with Dynatrace version 1.266. Its replacement is Settings API with the Metric events (builtin:anomaly-detection.metric-events) schema. We recommend that you migrate to the new API at your earliest convenience.

The migration affects endpoint URLs, query parameters, and response/request body parameters, as well as the scope of the token for the request.

Base URL

new Settings 2.0old Metric events
/api/v2/settings/config/v1/anomalyDetection/metricEvents

Authentication token scope

new Settings 2.0old Metric events
Read settings (settings.read)
Write settings (settings.write)		Read configuration (ReadConfig)
Write configuration (WriteConfig)

Parameters

To learn about new query/body parameters, see the documentation of individual requests in Settings API.

In the Settings 2.0 framework, each metric event is represented by a settings object. An object contains some metadata (like the scope or creation timestamp) and the configuration itself, encapsulated in the value object. To learn about the parameters of a metric event configuration, query the Metric events (builtin:anomaly-detection.metric-events) schema with the GET a schema request. The configuration differs from the Metric events API—check the examples below to see the differences.

Examples

Here are some examples of differences in API usage.

List metric events

To list all metric events, you need the GET objects request. In query parameters, set schemaIds to builtin:anomaly-detection.metric-events and scope to environment.

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects?schemaIds=builtin:anomaly-detection.metric-events&scopes=environment

Response body

json
[
    {
      "objectId": "vu9U3hXa3q0AAAABACdidWlsdGluOmFub21hbHktZGV0ZWN0aW9uLm1ldHJpYy1ldmVudHMABnRlbmFudAAGdGVuYW50ACQ0NWE4ZjNiNy0wNWMxLTNjM2YtOGMzOC04MTJjOGIxOTA4YWO-71TeFdrerQ",
      "value": {
        "enabled": false,
        "summary": "Mobile app 90th percentile",
        "queryDefinition": {
          "type": "METRIC_KEY",
          "metricKey": "builtin:apps.other.uaDuration.osAndVersion",
          "aggregation": "PERCENTILE90",
          "entityFilter": {
            "dimensionKey": "dt.entity.device_application",
            "conditions": [
              {
                "type": "NAME",
                "operator": "EQUALS",
                "value": "📱 easyTravel Mobile"
              }
            ]
          },
          "dimensionFilter": []
        },
        "modelProperties": {
          "type": "STATIC_THRESHOLD",
          "threshold": 1140000.0,
          "alertOnNoData": false,
          "alertCondition": "ABOVE",
          "violatingSamples": 3,
          "samples": 5,
          "dealertingSamples": 5
        },
        "eventTemplate": {
          "title": "Mobile 90th percentile",
          "description": "The {metricname} value of {severity} was {alert_condition} your custom threshold of {threshold}.",
          "eventType": "CUSTOM_ALERT",
          "davisMerge": false,
          "metadata": []
        },
        "eventEntityDimensionKey": "dt.entity.device_application",
        "legacyId": "5be3e027-0b1a-456f-9f69-4661007e8140"
      }
    }
]

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/config/v1/anomalyDetection/metricEvents

Response body

json
{
  "values": [
    {
      "id": "5be3e027-0b1a-456f-9f69-4661007e8140",
      "name": "Mobile 90th percentile",
      "description": "The {metricname} value of {severity} was {alert_condition} your custom threshold of {threshold}."
    }
  ]
}

Create a metric event

In this example, we create a metric event that monitors the free disk space on hosts belonging to a certain management zone. We use the static threshold of 10% and raise an informational event if the metric goes below this value.

To create a metric event, you need the POST an object request. In the request body, set schemaId to builtin:anomaly-detection.metric-events and scope to environment. Provide the metric event configuration in the value object.

The response contains the ID of the object that you need to manage the settings.

Request URL

plaintext
POST https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects

Request body

json
[
  {
  "scope": "environment",
  "schemaId": "builtin:anomaly-detection.metric-events",
  "value": {
    "enabled": false,
    "summary": "Too little disk space",
    "queryDefinition": {
      "type": "METRIC_KEY",
      "metricKey": "builtin:host.disk.free",
      "aggregation": "AVG",
      "managementZone": "-4375000063077304495",
      "entityFilter": {
        "dimensionKey": "dt.entity.host",
        "conditions": []
      },
      "dimensionFilter": []
    },
    "modelProperties": {
      "type": "STATIC_THRESHOLD",
      "threshold": 15.0,
      "alertOnNoData": false,
      "alertCondition": "BELOW",
      "violatingSamples": 3,
      "samples": 5,
      "dealertingSamples": 5
    },
    "eventTemplate": {
      "title": "Disk space is running out",
      "description": "The {metricname} value was {alert_condition} normal behavior.",
      "eventType": "INFO",
      "metadata": []
    },
    "eventEntityDimensionKey": "dt.entity.disk"
  }
}
]

Response body

json
[
  {
    "code": 200,
    "objectId": "vu9U3hXa3q0AAAABACdidWlsdGluOmFub21hbHktZGV0ZWN0aW9uLm1ldHJpYy1ldmVudHMABnRlbmFudAAGdGVuYW50ACRiYTRmYmU4MC00ODU0LTMwOTItYjZmMC1jNDFjNjgzOGI0OGK-71TeFdrerQ"
  }
]

Request URL

plaintext
POST https://mySampleEnv.live.dynatrace.com/config/v1/anomalyDetection/metricEvents

The response contains the ID of the configuration that you need to manage the settings.

Request body

json
{
  "metricId": "builtin:host.disk.free",
  "name": "Too little disk space",
  "description": "The {metricname} value was {alert_condition} normal behavior.",
  "severity": "INFO",
  "enabled": false,
  "disabledReason": "NONE",
  "warningReason": "NONE",
  "monitoringStrategy": {
    "type": "STATIC_THRESHOLD",
    "samples": 5,
    "violatingSamples": 3,
    "dealertingSamples": 5,
    "alertCondition": "BELOW",
    "alertingOnMissingData": false,
    "threshold": 15.0
  }
}

Response body

json
{
  "id": "c4dfc9ee-852d-4ac5-8fed-6eea75c97926",
  "name": "gToo little disk space",
  "description": "The {metricname} value was {alert_condition} normal behavior."
}

Edit a metric event

In this example, we modify the metric event created in the previous example. We lower the threshold to 10% and modify the event message.

To edit a metric event, you need the PUT an object request.

Request URL

plaintext
PUT https://mySampleEnv.live.dynatrace.com/api/v2/settings/objects/vu9U3hXa3q0AAAABACdidWlsdGluOmFub21hbHktZGV0ZWN0aW9uLm1ldHJpYy1ldmVudHMABnRlbmFudAAGdGVuYW50ACRiYTRmYmU4MC00ODU0LTMwOTItYjZmMC1jNDFjNjgzOGI0OGK-71TeFdrerQ

Request body

json
{
  "scope": "environment",
  "schemaId": "builtin:anomaly-detection.metric-events",
  "value": {
    "enabled": false,
    "summary": "Too little disk space",
    "queryDefinition": {
      "type": "METRIC_KEY",
      "metricKey": "builtin:host.disk.free",
      "aggregation": "AVG",
      "managementZone": "-4375000063077304495",
      "entityFilter": {
        "dimensionKey": "dt.entity.host",
        "conditions": []
      },
      "dimensionFilter": []
    },
    "modelProperties": {
      "type": "STATIC_THRESHOLD",
      "threshold": 10.0,
      "alertOnNoData": false,
      "alertCondition": "BELOW",
      "violatingSamples": 3,
      "samples": 5,
      "dealertingSamples": 5
    },
    "eventTemplate": {
      "title": "Disk space is running out",
      "description": "The {metricname} value was {alert_condition} {threshold}%.",
      "eventType": "INFO",
      "metadata": []
    },
    "eventEntityDimensionKey": "dt.entity.disk"
  }
}

Response body

json
{
  "code": 200,
  "objectId": "vu9U3hXa3q0AAAABACdidWlsdGluOmFub21hbHktZGV0ZWN0aW9uLm1ldHJpYy1ldmVudHMABnRlbmFudAAGdGVuYW50ACRiYTRmYmU4MC00ODU0LTMwOTItYjZmMC1jNDFjNjgzOGI0OGK-71TeFdrerQ"
}

Request URL

plaintext
PUT https://mySampleEnv.live.dynatrace.com/config/v1/anomalyDetection/metricEvents/2640173c-e9a8-31dc-9584-696969c716f5

Request body

json
{
  "metricId": "builtin:host.disk.free",
  "name": "Too little disk space",
  "description": "The {metricname} value was {alert_condition} {threshold}%.",
  "severity": "INFO",
  "enabled": false,
  "disabledReason": "NONE",
  "warningReason": "NONE",
  "monitoringStrategy": {
    "type": "STATIC_THRESHOLD",
    "samples": 5,
    "violatingSamples": 3,
    "dealertingSamples": 5,
    "alertCondition": "BELOW",
    "alertingOnMissingData": false,
    "threshold": 10.0
  }
}
Related topics
  • Settings API

    Find out what the Dynatrace Settings API offers.

  • Anomaly detection API - Metric events

    Learn what the Dynatrace Anomaly detection API for metric events offers.