Migrate from Events API v1 to Events API v2

Events API v1 has been deprecated with Dynatrace version 1.243. Its replacement is Events API v2. 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 request authentication.

New features

Events API v2 offers you the following new features:

The entity selector helps you to filter events in read requests and ingest events that affect multiple entities.
Improved event filtering via an event selector.
Unified timeframe selector.
Event properties endpoints.
Event types endpoints.

Licensing

The ingestion of custom events consumes Davis Data Units (DDUs) from the events pool.

Base URL

new Events v2	old Events v1
`/api/v2/events`	`/api/v1/events`

Authentication token scope

new Events v2	old Events v1
Read events (`events.read`) Ingest events (`events.ingest`)	Access problem and event feed, metrics, and topology (`DataExport`)

Parameters

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

Examples

Here are some examples of differences in API usage.

List events within a timeframe

In this example, we query a list of open availability events on hosts that happened within the last two hours.

Events v2Events v1

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/api/v2/events?eventSelector=eventType("AVAILABILITY_EVENT"),status("OPEN")&from=now-2h&entitySelector=type("HOST")

Response body

json
{
    "totalCount": 28,
    "pageSize": 2,
    "nextPageKey": "AQANMTY2OTY0NDE2NjAwOQEADTE2Njk2NTEzNjYwMDkBADtTdHJpbmcoVDFCRlRnPT0pLUxvbmcoMTg0YmVlMjU1NjkpLUxvbmcoYTdjZjQ2NjZlNjIwZjMyMSktMgEAAAACAQAuZXZlbnRUeXBlKCJBVkFJTEFCSUxJVFlfRVZFTlQiKSxzdGF0dXMoIk9QRU4iKQEADHR5cGUoIkhPU1QiKQA=",
    "events": [
        {
            "eventId": "-9195326388738983252_1669651221408",
            "startTime": 1669651221408,
            "endTime": -1,
            "eventType": "AVAILABILITY_EVENT",
            "title": "No process found for rule Oracle listener",
            "entityId": {
                "entityId": {
                    "id": "HOST-E371A974A078CC54",
                    "type": "HOST"
                },
                "name": "frontend-dev"
            },
            "properties": [
                {
                    "key": "Event source",
                    "value": "Process availability"
                },
                {
                    "key": "Message",
                    "value": "Missing process matching rule named Oracle listener"
                },
                {
                    "key": "custom.message-process-av",
                    "value": "The {dt.event.title} is on deployment version: {dt.event.deployment.version}"
                },
                {
                    "key": "dt.event.group_label",
                    "value": "Availability event"
                },
                {
                    "key": "dt.event.impact_level",
                    "value": "Infrastructure"
                },
                {
                    "key": "dt.event.is_rootcause_relevant",
                    "value": "true"
                },
                {
                    "key": "dt.event.timeout",
                    "value": "4"
                },
                {
                    "key": "dt.event.title",
                    "value": "No process found for rule Oracle listener"
                }
            ],
            "status": "OPEN",
            "correlationId": "458a73c38677f1ac",
            "entityTags": [
                {
                    "context": "CONTEXTLESS",
                    "key": "frontend",
                    "stringRepresentation": "frontend"
                },
                {
                    "context": "CONTEXTLESS",
                    "key": "stage",
                    "value": "dev",
                    "stringRepresentation": "stage:dev"
                }
            ],
            "managementZones": [
                {
                    "id": "6143976176513989654",
                    "name": "Infrastructure Linux"
                },
                {
                    "id": "4067143719293196613",
                    "name": "dev"
                },
                {
                    "id": "-6114370715062110014",
                    "name": "frontent"
                }
            ],
            "underMaintenance": false,
            "suppressAlert": false,
            "suppressProblem": false,
            "frequentEvent": false
        },
        {
            "eventId": "-6354783141434952927_1669649814889",
            "startTime": 1669649814889,
            "endTime": -1,
            "eventType": "AVAILABILITY_EVENT",
            "title": "Host unavailable",
            "entityId": {
                "entityId": {
                    "id": "HOST-FD01FA52FB10B433",
                    "type": "HOST"
                },
                "name": "GDNVTUBU2004-1"
            },
            "properties": [
                {
                    "key": "dt.event.group_label",
                    "value": "Availability event"
                },
                {
                    "key": "dt.event.impact_level",
                    "value": "Infrastructure"
                },
                {
                    "key": "dt.event.is_rootcause_relevant",
                    "value": "true"
                },
                {
                    "key": "dt.event.timeout",
                    "value": "5"
                },
                {
                    "key": "dt.event.title",
                    "value": "Host unavailable"
                }
            ],
            "status": "OPEN",
            "correlationId": "360ad37a6f4de7d0",
            "entityTags": [
                {
                    "context": "CONTEXTLESS",
                    "key": "OS",
                    "value": "Linux",
                    "stringRepresentation": "OS:Linux"
                }
            ],
            "managementZones": [
                {
                    "id": "6143976176513989654",
                    "name": "Linux"
                },
                {
                    "id": "4067143719293196613",
                    "name": "dev"
                }
            ],
            "underMaintenance": false,
            "suppressAlert": false,
            "suppressProblem": false,
            "frequentEvent": false
        }
    ],
    "warnings": []
}

In Events API v1, it is not possible to filter the events feed by event status. Also, it is not possible to select multiple entities via the entity selector. You can only specify particular entities. For illustration purposes, the example payload shows the same events, but you would have to find them in the payload by external means.

Request URL

plaintext
GET https://mySampleEnv.live.dynatrace.com/api/v1/events?relativeTime=2hours?eventType=AVAILABILITY_EVENT

Response body

json
{
  "nextEventStartTms": 1669639936928,
  "nextEventId": -3132566662524695739,
  "nextCursor": "AgEAAAGEvd8xRAEAAAGEvk0ORAAAAQA8U3RyaW5nKFQxQkZUZz09KS1Mb25nKDE4NGJlNGI5YmEwKS1Mb25nKGQ0ODZlMzM3YWNmYzBiNDUpLTk2",
  "from": 1669632831812,
  "to": 1669640031812,
  "totalEventCount": 25703,
  "events": [
    {
        "eventId": -9195326388738983252,
        "startTime": 1669651221408,
        "endTime": 1669658492185,
        "entityId": "HOST-E371A974A078CC54",
        "entityName": "frontend-dev",
        "severityLevel": "AVAILABILITY",
        "impactLevel": "INFRASTRUCTURE",
        "eventType": "AVAILABILITY_EVENT",
        "eventStatus": "OPEN",
        "tags": [
            {
                "context": "CONTEXTLESS",
                "key": "frontend"
            },
            {
                "context": "CONTEXTLESS",
                "key": "stage",
                "value": "dev"
            }
        ],
        "id": "-9195326388738983252_1669651221408",
        "customProperties": {
            "custom.message-process-av": "The {dt.event.title} is on deployment version: {dt.event.deployment.version}",
            "Event source": "Process availability",
            "Message": "Missing process matching rule named Oracle listener"
        },
        "correlationId": "458a73c38677f1ac",
        "source": "builtin"
    },
    {
        "eventId": -6354783141434952927,
        "startTime": 1669649814889,
        "endTime": 1669652093491,
        "entityId": "HOST-FD01FA52FB10B433",
        "entityName": "GDNVTUBU2004-1",
        "severityLevel": "AVAILABILITY",
        "impactLevel": "INFRASTRUCTURE",
        "eventType": "AVAILABILITY_EVENT",
        "eventStatus": "OPEN",
        "tags": [
            {
                "context": "CONTEXTLESS",
                "key": "OS",
                "value": "Linux"
            }
        ],
        "id": "-6354783141434952927_1669649814889",
        "correlationId": "360ad37a6f4de7d0",
        "source": "builtin"
    }
  ]
}

Ingest a third-party event

In this example, we ingest a custom info event affecting all hosts whose hostname begins with prod.

Events v2Events v1

Request URL

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

Request body

json
{
    "eventType": "AVAILABILITY_EVENT",
    "title": "Critical service outage",
    "timeout": 30,
    "entitySelector": "type(HOST),entityName.startsWith(prod)",
    "allowDavisMerge": false,
    "properties": {
      "custom property 1": "my property value 1",
      "custom property 2": "my property value 2"
    }
}

In the Events API v1, it is not possible to select multiple entities via the entity selector. You have to either specify each entity or rely on tags.

Request URL

plaintext
POST https://mySampleEnv.live.dynatrace.com/api/v1/events

Request body

json
{
  "eventType": "AVAILABILITY_EVENT",
  "title": "Critical service outage",
  "description": "REST example",
  "timeoutMinutes": 30,
    "attachRules": {
    "tagRule": [
       {
        "meTypes": [
          "HOST"
        ],
        "tags": [
          {
            "context": "CONTEXTLESS",
            "key": "stage",
            "value": "production"
          }
        ]
      }
    ]
  },
  "source": "REST API"
}