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.0
old Metric events
/api/v2/settings
/config/v1/anomalyDetection/metricEvents

Authentication token scope

new Settings 2.0
old 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

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

Response body

[
    {
      "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"
      }
    }
]

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

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

Request body

[
  {
  "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

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

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

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

Request body

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

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

Related topics