Synthetic monitors API - POST a monitor
Creates a new synthetic monitor.
The configuration of the new monitor is passed via its JSON script.
POST | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/v1/synthetic/monitors |
SaaS | https://{your-environment-id}.live.dynatrace.com/api/v1/synthetic/monitors | |
Environment ActiveGate | https://{your-activegate-domain}/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 | Synthetic | 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 | Anomaly | The anomaly detection configuration. | optional |
enabled | boolean | The monitor is enabled ( | required |
frequencyMin | integer | The frequency of the monitor, in minutes. You can use one of the following values: | 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 | Tag | A set of tags assigned to the monitor. You can specify only the value of the tag here and the | required |
type | string | Defines the actual set of fields depending on the value. See one of the following objects:
| required |
The AnomalyDetection
object
The anomaly detection configuration.
Element | Type | Description | Required |
---|---|---|---|
loadingTimeThresholds | Loading | Performance thresholds configuration. | required |
outageHandling | Outage | Outage handling configuration. | required |
The LoadingTimeThresholdsPolicyDto
object
Performance thresholds configuration.
Element | Type | Description | Required |
---|---|---|---|
enabled | boolean | Performance threshold is enabled ( | required |
thresholds | Loading | 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. | 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 ( | required |
globalOutagePolicy | Global | Global outage handling configuration. | optional |
localOutage | boolean | When enabled ( | required |
localOutagePolicy | Local | 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 | 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 | 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 | Entity | Success. The new synthetic monitor has been created. The response contains the Dynatrace entity ID of the new monitor. |
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