Synthetic monitors API - POST a monitor

Creates a new synthetic monitor.

The configuration of the new monitor is passed via its JSON script.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/monitors
Environment ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/v1/synthetic/monitors

Authentication

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

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

Parameters

To find all model variations that depend on the type of the model, see JSON models.

Parameter
Type
Description
In
Required
body

The JSON body of the request, containing parameters of the new synthetic monitor.

body
optional

Request body objects

The SyntheticMonitorUpdate object

The synthetic monitor update.

The actual set of fields depends the type of the monitor. Find the list of actual objects in the description of the type field or see Synthetic monitors API - JSON models.

Element
Type
Description
Required
anomalyDetection

The anomaly detection configuration.

optional
enabled
boolean

The monitor is enabled (true) or disabled (false).

required
frequencyMin
integer

The frequency of the monitor, in minutes.

You can use one of the following values: 5, 10, 15, 30, and 60.

required
locations
string[]

A list of locations from which the monitor is executed.

To specify a location, use its entity ID.

required
manuallyAssignedApps
string[]

A set of manually assigned applications.

required
name
string

The name of the monitor.

required
script
object

The script of a browser or HTTP monitor.

required
tags

A set of tags assigned to the monitor.

You can specify only the value of the tag here and the CONTEXTLESS context and source 'USER' will be added automatically. But preferred option is usage of TagWithSourceDto model.

required
type
string

Defines the actual set of fields depending on the value. See one of the following objects:

  • BROWSER -> BrowserSyntheticMonitorUpdate
  • HTTP -> HttpSyntheticMonitorUpdate
  • BROWSER
  • HTTP
required

The AnomalyDetection object

The anomaly detection configuration.

Element
Type
Description
Required
loadingTimeThresholds

Performance thresholds configuration.

optional
outageHandling

Outage handling configuration.

optional

The LoadingTimeThresholdsPolicyDto object

Performance thresholds configuration.

Element
Type
Description
Required
enabled
boolean

Performance threshold is enabled (true) or disabled (false).

required
thresholds

The list of performance threshold rules.

required

The LoadingTimeThreshold object

The performance threshold rule.

Element
Type
Description
Required
eventIndex
integer

Specify the event to which an ACTION threshold applies.

optional
requestIndex
integer

Specify the request to which an ACTION threshold applies.

optional
type
string

The type of the threshold: total loading time or action loading time.

  • ACTION
  • TOTAL
required
valueMs
integer

Notify if monitor takes longer than X milliseconds to load.

required

The OutageHandlingPolicy object

Outage handling configuration.

Element
Type
Description
Required
globalOutage
boolean

When enabled (true), generate a problem and send an alert when the monitor is unavailable at all configured locations.

required
globalOutagePolicy

Global outage handling configuration.

optional
localOutage
boolean

When enabled (true), generate a problem and send an alert when the monitor is unavailable for one or more consecutive runs at any location.

required
localOutagePolicy

Local outage handling configuration.

Alert if affectedLocations of locations are unable to access the web application consecutiveRuns times consecutively.

required
retryOnError
boolean

Schedule retry if browser monitor execution results in a fail. For HTTP monitors this property is ignored.

optional

The GlobalOutagePolicy object

Global outage handling configuration.

Element
Type
Description
Required
consecutiveRuns
integer

Alert if all locations are unable to access the web application X times consecutively.

required

The LocalOutagePolicy object

Local outage handling configuration.

Alert if affectedLocations of locations are unable to access the web application consecutiveRuns times consecutively.

Element
Type
Description
Required
affectedLocations
integer

The number of affected locations to trigger an alert.

required
consecutiveRuns
integer

The number of consecutive fails to trigger an alert.

required

The TagWithSourceInfo object

Tag with source of a Dynatrace entity.

Element
Type
Description
Required
context
string

The origin of the tag, such as AWS or Cloud Foundry.

Custom tags use the CONTEXTLESS value.

  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_CLOUD
  • KUBERNETES
required
key
string

The key of the tag.

Custom tags have the tag value here.

required
source
string

The source of the tag, such as USER, RULE_BASED or AUTO

  • AUTO
  • RULE_BASED
  • USER
optional
value
string

The value of the tag.

Not applicable to custom tags.

optional

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.

{
  "anomalyDetection": {
    "loadingTimeThresholds": {
      "enabled": true,
      "thresholds": [
        {
          "requestIndex": 1,
          "type": "TOTAL",
          "valueMs": 100
        }
      ]
    },
    "outageHandling": {
      "globalOutage": true,
      "localOutage": true,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
      }
    }
  },
  "enabled": true,
  "events": [],
  "frequencyMin": 5,
  "keyPerformanceMetrics": {
    "loadActionKpm": "VISUALLY_COMPLETE",
    "xhrActionKpm": "VISUALLY_COMPLETE"
  },
  "locations": [
    "GEOLOCATION-9999453BE4BDB3CD"
  ],
  "manuallyAssignedApps": [
    "APPLICATION-4ADF0EF407C7C545"
  ],
  "name": "Browser Monitor Example",
  "script": {
    "configuration": {
      "device": {
        "deviceName": "Desktop",
        "orientation": "landscape"
      }
    },
    "events": [
      {
        "description": "Loading of \"example.com\"",
        "type": "navigate",
        "url": "http://example.com",
        "wait": {
          "waitFor": "page_complete"
        }
      }
    ],
    "type": "availability",
    "version": "1.0"
  },
  "tags": [
    "example"
  ],
  "type": "BROWSER"
}

Response

Response codes

Code
Type
Description
200

Success. The new synthetic monitor has been created. The response contains the Dynatrace entity ID of the new monitor.

4XX

Client side error.

5XX

Server side error.

Response body objects

The EntityIdDto object

A DTO for entity ID.

Element
Type
Description
entityId
string

Entity ID to be transferred

Response body JSON model

{
  "entityId": "string"
}

Example

In this example, the request creates a simple browser monitor that navigates to dynatrace.com.

The monitor is executed every 10 minutes from one location, which has the ID of GEOLOCATION-0A41430434C388A9. A problem will be raised if the website is unavailable for three consecutive runs. A notification is sent if the website takes longer than 500 milliseconds to load.

The API token is passed in the Authorization header.

The response contains the entity ID of the newly created monitor.

Since the request body is lengthy, it is truncated in this example Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Before using it, make sure that the location from the example is available in your environment. You can fetch the list of available locations with the GET all synthetic locations call. If the location is not available, replace it with any location you're using.

Curl

curl -X POST \
  https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/monitors \
  -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \
  -d '{<truncated - see the Request body section >}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v1/synthetic/monitors

Request body

{
  "frequencyMin": 10,
  "anomalyDetection": {
    "outageHandling": {
      "globalOutage": true,
      "localOutage": false,
      "localOutagePolicy": {
        "affectedLocations": 1,
        "consecutiveRuns": 3
      }
    },
    "loadingTimeThresholds": {
      "enabled": true,
      "thresholds": [
        {
          "type": "total",
          "valueMs": 500
        }
      ]
    }
  },
  "type": "BROWSER",
  "name": "restExample",
  "locations": ["GEOLOCATION-0A41430434C388A9"],
  "enabled": true,
  "script": {
    "configuration": {
      "device": {
        "orientation": "landscape",
        "deviceName": "Desktop"
      }
    },
    "type": "clickpath",
    "version": "1.0",
    "events": [
      {
        "type": "navigate",
        "wait": {
          "waitFor": "page_complete"
        },
        "description": "navigate to main page ",
        "url": "https://www.dynatrace.com"
      }
    ]
  },
  "tags": ["restExample"]
}

Response body

{
  "entityId": "SYNTHETIC_TEST-00000000000254E2"
}

Response code

200

Related topics