How do I push custom events from 3rd party systems?

The events REST endpoint enables 3rd party integrations to push custom events to one or more monitored entities via the API. The intent of this interface is to allow 3rd party systems, such as CI platforms (Bamboo, Electric Cloud, etc.) to provide additional detail for Dynatrace automated root cause analysis.

The events API offers a set of semantically predefined event types that allow the Dynatrace problem correlation engine to correctly handle information provided by external systems. The predefined semantics of these event types allows for more precise root cause detection.

Each event, regardless of type, must provide the following common meta information:

  • eventType: The predefined event type, such as 'CUSTOM_DEPLOYMENT' or 'CUSTOM_ANNOTATION'.
  • start: Optional start timestamp of the event in UTC milliseconds (for example 1495200637630). The actual time is used for the event if no start timestamp is provided.
  • end: Optional end timestamp of the event in UTC milliseconds. The actual time is used if no end timestamp is provided.
  • attachRules: A complex structure that contains attachment rules that define which monitored entities the event is to be attached to. One attach rules is entityIds, which contains an array of entity identifiers (for example, [ "APPLICATION-B66B773D12C49189" ]. Another possible attach rule is tagRule that takes a component type and a tag to attach your custom event on all components of that type that contain the given tag. See below for an example for an attach rule:
"attachRules": {
  "entityIds" : ["APPLICATION-B66B773D12C49189"],
    "tagRule" : [{
        "meTypes" : ["SERVICE"],
        "tags" : ["PRODUCTION"]
    }]
}

The tag attach rule can also contain multiple component types and tags as shown within the example below:

"attachRules" : {
  "entityIds" : [ "HOST-A56B773D12C49189", "HOST-C55B773D12C49189" ],
  "tagRule" : [ {
    "meTypes" : [ "APPLICATION", "AWS_LAMBDA_FUNCTION" ],
    "tags" : [ {
      "context" : "CONTEXTLESS",
      "key" : "t1"
    }, {
      "context" : "CONTEXTLESS",
      "key" : "t2"
    } ]
  } ]
}

Multiple tags in one tagRule match only if a component has all the tags. Matching one of multiple tags can be done by specifying multiple tagRule entries, each with one tag.

3rd party systems can push the following predefined events into a monitored environment:

Deployment events: (CUSTOM_DEPLOYMENT)

This event type is used to inform a Dynatrace environment of a deployment that is triggered by continous integration or IT automation tools (for example, Bamboo, Electric Cloud, Ansible Tower, etc). These tools provide a lot of meta information about the project and configuration that was deployed, such as project name, package version, artifactory link, remediation actions, and more.

Deployment events can provide the following predefined meta information:

  • deploymentName: A string identifier for the deployment that was triggered.
  • deploymentVersion: A version string for the deployment.
  • deploymentProject: Project name of the deployed package.
  • remediationAction: Link to the deployment related remediation action within the external tool.
  • ciBackLink: Link to the deployed artifact within the 3rd party system.
  • source: Specifies the name or identifier for the external tool that provided the custom deployment event.
  • timeseriesIds: Optional array of timeseries IDs that are related to the event.
  • customProperties: Dictionary of custom key value pairs that can be used to send additional information along with the deployment event.

Annotation events: (CUSTOM_ANNOTATION)

This event type is used to annotate a monitored entity within Dynatrace. Possible use cases include informing about important changes that were made within the monitored environment.

Annotations can provide the following predefined meta information:

  • annotationType: A string identifier for the type that is used to group the annotations (for example, DNS route changed).
  • annotationDescription: A textual description of the annotation (for example, DNS route was changed to x.labs.com).
  • source: Specifies the name or identifier of the external tool that provided the custom annotation event.
  • customProperties: Dictionary of custom key value pairs that can be used to send additional information along with the annotation event.

Examples

The following example shows a typical payload of an external deployment event:

{
  "start":1495200637630,
  "end":1495200637630,
  "eventType": "CUSTOM_DEPLOYMENT",
  "attachRules": { 
    "entityIds" : ["APPLICATION-B66B773D12C49189"],
      "tagRule" : [{
        "meTypes" : ["SERVICE"],
        "tags" : ["PRODUCTION"]
      }]
  },
  "deploymentName":"easyTravel",
  "deploymentVersion":"1.0",
  "deploymentProject":"easyTravel",
  "remediationAction":"http://revertMe",
  "ciBackLink":"http://myBacklink",
  "source":"CloudFoundry",
  "customProperties":{
    "CI Tool": "Jenkins",
    "Jenkins Build Number": "12321",
    "Git commit": "23422323233332"
  }
}

The following HTTP POST request pushes a new annotation event to one of your applications to inform about a major change within the DNS route:

https://{id}.live.dynatrace.com/api/v1/events/

The following example shows how to push a new annotation event to one of your applications:

{
  "start":1495200637630,
  "end":1495200637630,
  "eventType": "CUSTOM_ANNOTATION",
  "attachRules":
  {
    "entityIds": [ "APPLICATION-B66B773D12C49189" ]
  },
  "annotationType" : "DNS route changed",
  "source" : "OpsControl",
  "annotationDescription" : "We changed the DNS configration",
  "timeseriesIds":[],
  "customProperties":
  {
    "original": "x.rxlab.com",
    "changed": "x.dtlab.com"
  }
}