Events API v2 - POST an event

Ingests a custom event to Dynatrace.

The request consumes an application/json payload.

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

POST	SaaS	`https://{your-environment-id}.live.dynatrace.com/api/v2/events/ingest`
POST	Environment ActiveGateCluster ActiveGate	`https://{your-activegate-domain}:9999/e/{your-environment-id}/api/v2/events/ingest`

Authentication

To execute this request, you need an access token with events.ingest scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter

Type

Description

Required

body

EventIngest

The JSON body of the request. Contains properties of the new event.

body

optional

Request body objects

The `EventIngest` object

The configuration of an event to be ingested.

Element

Type

Description

Required

endTime

integer

The end time of the event, in UTC milliseconds.

If not set, the start time plus timeout is used.

optional

entitySelector

string

The entity selector, defining a set of Dynatrace entities to be associated with the event.

Only entities that have been active within the last 24 hours can be selected.

If not set, the event is associated with the environment (dt.entity.environment) entity.

optional

eventType

string

The type of the event.

AVAILABILITY_EVENT
CUSTOM_ALERT
CUSTOM_ANNOTATION
CUSTOM_CONFIGURATION
CUSTOM_DEPLOYMENT
CUSTOM_INFO
ERROR_EVENT
MARKED_FOR_TERMINATION
PERFORMANCE_EVENT
RESOURCE_CONTENTION_EVENT

required

properties

object

A map of event properties.

Keys with prefix dt.* are generally disallowed, with the exceptions of dt.event.*, dt.davis.* and dt.entity.*. These reserved keys may be used to set event properties with predefined semantics within the Dynatrace product. dt.entity.* keys may be used to provide additional information on an event, but will not lead to the event being tied to the specified entities. All other keys are interpreted as user-defined event properties.

Values of Dynatrace-reserved properties must fulfill the requirements of the respective property.

A maximum of 100 properties can be specified. A property key is allowed to contain up to 100 characters. A property value is allowed to contain up to 4096 characters.

optional

startTime

integer

The start time of the event, in UTC milliseconds.

If not set, the current timestamp is used.

Depending on the event type, the start time must not lie in the past more than 6 hours for problem-opening events and 30 days for info events.

Depending on the event type, the start time must not lie in the future more than 5 minutes for problem-opening events and 7 days for info events.

optional

timeout

integer

The timeout of the event, in minutes.

If not set, 15 is used.

The timeout will automatically be capped to a maximum of 360 minutes (6 hours).

Problem-opening events can be refreshed and therefore kept open by sending the same payload again.

optional

title

string

The title of the event.

required

Request body JSON model

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request.

{
  "endTime": 1,
  "entitySelector": "string",
  "eventType": "AVAILABILITY_EVENT",
  "properties": {},
  "startTime": 1,
  "timeout": 1,
  "title": "string"
}

Response

Response codes

Code

Type

Description

201

EventIngestResults

The event ingest request was received by the server. The response body indicates for each event whether its creation was successful.

4XX

ErrorEnvelope

Client side error.

5XX

ErrorEnvelope

Server side error.

Response body objects

The `EventIngestResults` object

The results of an event ingest.

Element

Type

Description

eventIngestResults

EventIngestResult[]

The result of each created event report.

reportCount

integer

The number of created event reports.

The `EventIngestResult` object

The result of a created event report.

Element

Type

Description

correlationId

string

The correlation ID of the created event.

status

string

The status of the ingestion.

INVALID_ENTITY_TYPE
INVALID_METADATA
INVALID_TIMESTAMPS
OK

Response body JSON model

{
  "eventIngestResults": [
    {
      "correlationId": "string",
      "status": "INVALID_ENTITY_TYPE"
    }
  ],
  "reportCount": 1
}

Examples

An operations team wants to push a Marked for termination event to all the hosts that are planned to be removed. They also want to include the purpose for the deletion and a job identifier. The hosts to be removed are gathered in a designated host group.

In this example, the request sends a Marked for termination event to hosts that are planned to be removed. Such hosts are identified by the cloud-burst-hosts host group. The event automatically applies to all hosts that are part of the group. The purpose for termination and automation job number are provided as additional information.

The API token is passed in the Authorization header.

Curl

curl --request POST \
  --url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
  --header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventType": "MARKED_FOR_TERMINATION",
    "title": "Planned host downscale",
    "entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
    "properties": {
        "job.number": "21234346"
    }
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest

Request body

{
    "eventType": "MARKED_FOR_TERMINATION",
    "title": "Planned host downscale",
    "entitySelector": "type(HOST),fromRelationship.isInstanceOf(type(HOST_GROUP),entityName(cloud-burst-hosts))",
    "properties": {
        "job.number": "21234346"
    }
}

Response body

{
  "reportCount": 2,
  "eventIngestResults": [
    {
      "correlationId": "41f5d263011a6c9a",
      "status": "OK"
    },
    {
      "correlationId": "80eae4d163cc5760",
      "status": "OK"
    }
  ]
}

Response code

201

A DevOps team wants to connect their load test tool with Dynatrace to annotate a service that is currently undergoing a load test. Later, when Dynatrace raises a problem caused by the load test, the problem details will include this information, simplifying the triage process.

In this example, the request sends a Custom info event to the BookingService service, marking it as a target of a load test.

The API token is passed in the Authorization header.

Curl

curl --request POST \
  --url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
  --header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventType": "CUSTOM_INFO",
    "title": "Loadtest start",
    "timeout": 30,
    "entitySelector": "type(SERVICE),entityName.equals(BookingService)",
    "properties": {
        "Tool": "MyLoadTool",
        "Load per minute": "100",
        "Load pattern": "production"
    }
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest

Request body

{
    "eventType": "CUSTOM_INFO",
    "title": "Loadtest start",
    "timeout": 30,
    "entitySelector": "type(SERVICE),entityName.equals(BookingService)",
    "properties": {
        "Tool": "MyLoadTool",
        "Load per minute": "100",
        "Load pattern": "production"
    }
}

Response body

{
  "reportCount": 1,
  "eventIngestResults": [
    {
      "correlationId": "eba82f647696e485",
      "status": "OK"
    }
  ]
}

Response code

201

The operations team of a large retailer wants to trigger an alert in Dynatrace whenever their catalog update batch process fails. They want to create an event and alert in Dynatrace, but they don’t want Davis to merge this externally created event with any larger incident.

In this example, the request sends an Error event to the BookingService service, indicating a failed update. The dt.event.allow_davis_merge property is set to false, preventing Davis from merging this event with any other event.

The API token is passed in the Authorization header.

Curl

curl --request POST \
  --url https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest \
  --header 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  --header 'Content-Type: application/json' \
  --data '{
    "eventType": "ERROR_EVENT",
    "title": "Product catalog update failed",
    "timeout": 30,
    "entitySelector": "type(SERVICE),entityName.equals(BookingService)",
    "properties": {
        "dt.event.allow_davis_merge": "false",
        "Catalog": "APAC travels",
        "Batch processor": "travel-catalog"
    }
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v2/events/ingest

Request body

{
    "eventType": "ERROR_EVENT",
    "title": "Product catalog update failed",
    "timeout": 30,
    "entitySelector": "type(SERVICE),entityName.equals(BookingService)",
    "properties": {
        "dt.event.allow_davis_merge": "false",
        "Catalog": "APAC travels",
        "Batch processor": "travel-catalog"
    }
}

Response body

{
  "reportCount": 1,
  "eventIngestResults": [
    {
      "correlationId": "cefb7ae03ac720b6",
      "status": "OK"
    }
  ]
}

Response code

201

Events API v2 - POST an event

Authentication

Parameters

Request body objects

The EventIngest object

Request body JSON model

Response

Response codes

Response body objects

The EventIngestResults object

The EventIngestResult object

Response body JSON model

Examples

Curl

Request URL

Request body

Response body

Response code

Curl

Request URL

Request body

Response body

Response code

Curl

Request URL

Request body

Response body

Response code

Related topics

The `EventIngest` object

The `EventIngestResults` object

The `EventIngestResult` object