Synthetic NAM API v2 - Create synthetic monitor definition

Creates a new synthetic network availability monitor. For more details about network availability monitor creation, see Create a NAM monitor.

The request consumes and produces an application/json payload.

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

Authentication

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

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

Parameter

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. Contains the parameters of the monitor.

body
required

Request body objects

The SyntheticMultiProtocolMonitorUpdateDto object

Network availability monitor.

Element
Type
Description
Required
description
string

Monitor description

optional
enabled
boolean

If true, the monitor is enabled.

optional
frequencyMin
integer

The frequency of the monitor, in minutes.

optional
locations
string[]

The locations to which the monitor is assigned.

required
name
string

The name of the monitor.

required
performanceThresholds

Performance thresholds configuration.

optional
steps

The steps of the monitor.

required
syntheticMonitorOutageHandlingSettings

Outage handling configuration.

optional
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 SyntheticTagWithSourceDto model.

optional
type
string

Monitor type.

  • MULTI_PROTOCOL
required

The SyntheticMonitorPerformanceThresholdsDto object

Performance thresholds configuration.

Element
Type
Description
Required
enabled
boolean

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

optional
thresholds

The list of performance threshold rules.

optional

The SyntheticMonitorPerformanceThresholdDto object

The performance threshold rule.

Element
Type
Description
Required
aggregation
string

Aggregation type

  • AVG
  • MAX
  • MIN
optional
dealertingSamples
integer

Number of most recent non-violating request executions that closes the problem

optional
samples
integer

Number of request executions in analyzed sliding window (sliding window size)

optional
stepIndex
integer

Specify the step's index to which a threshold applies.

optional
threshold
integer

Notify if monitor request takes longer than X milliseconds to execute.

optional
violatingSamples
integer

Number of violating request executions in analyzed sliding window

optional

The SyntheticMultiProtocolMonitorStepDto object

The step of a network availability monitor.

Element
Type
Description
Required
constraints

The list of constraints which apply to all requests in the step.

required
name
string

Step name.

required
properties
object

The properties which apply to all requests in the step.

required
requestConfigurations

Request configurations.

required
requestType
string

Request type.

  • ICMP
  • TCP
  • DNS
required
targetFilter
string

Target filter.

optional
targetList
string[]

Target list.

required

The SyntheticMultiProtocolMonitorConstraintDto object

The network availability monitor constraint.

Element
Type
Description
Required
properties
object

The properties of the constraint.

required
type
string

Constraint type.

required

The SyntheticMultiProtocolRequestConfigurationDto object

The configuration of a network availability monitor request.

Element
Type
Description
Required
constraints

Request constraints.

required

The SyntheticMonitorOutageHandlingSettingsDto object

Outage handling configuration.

Element
Type
Description
Required
globalConsecutiveOutageCountThreshold
integer

Number of consecutive failures for all locations.

optional
globalOutages
boolean

Generate a problem and send an alert when the monitor is unavailable at all configured locations.

optional
localConsecutiveOutageCountThreshold
integer

Number of consecutive failures.

optional
localLocationOutageCountThreshold
integer

Number of failing locations.

optional
localOutages
boolean

Generate a problem and send an alert when the monitor is unavailable for one or more consecutive runs at any location.

optional

The SyntheticTagWithSourceDto object

The tag with source of a monitored entity.

Element
Type
Description
Required
context
string

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

Custom tags use the CONTEXTLESS value.

optional
key
string

The key of the tag.

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.

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.

{
  "description": "My network availability monitor description",
  "enabled": "true",
  "frequencyMin": "60",
  "locations": [
    "SYNTHETIC_LOCATION-D3A5BFD8676A4F19"
  ],
  "name": "My network availability monitor",
  "performanceThresholds": {
    "enabled": "true",
    "thresholds": [
      {
        "aggregation": "AVG",
        "dealertingSamples": "5",
        "samples": "5",
        "stepIndex": "0",
        "threshold": "200",
        "violatingSamples": "3"
      }
    ]
  },
  "steps": [
    {
      "constraints": [
        {
          "properties": {
            "operator": ">=",
            "value": "95"
          },
          "type": "SUCCESS_RATE_PERCENT"
        }
      ],
      "name": "Step 1",
      "properties": {
        "ICMP_IP_VERSION": "4",
        "ICMP_NUMBER_OF_PACKETS": "8",
        "ICMP_TIMEOUT_FOR_REPLY": "PT1S"
      },
      "requestConfigurations": [
        {
          "constraints": [
            {
              "properties": {
                "operator": "=",
                "value": "100"
              },
              "type": "ICMP_SUCCESS_RATE_PERCENT"
            }
          ]
        }
      ],
      "requestType": "ICMP",
      "targetFilter": "ipMask == 127.0.0.1/24",
      "targetList": [
        "127.0.0.1",
        "127.0.0.2"
      ]
    }
  ],
  "syntheticMonitorOutageHandlingSettings": {
    "globalConsecutiveOutageCountThreshold": "1",
    "globalOutages": "true",
    "localConsecutiveOutageCountThreshold": "3",
    "localLocationOutageCountThreshold": "3",
    "localOutages": "true"
  },
  "tags": [
    {
      "key": "sample key",
      "value": "sample value"
    },
    {
      "key": "sample key"
    }
  ],
  "type": "MULTI_PROTOCOL"
}

Response

Response codes

Code
Type
Description
200

Success

4XX

Client side error.

5XX

Server side error.

Response body objects

The MonitorEntityIdDto object

A DTO for monitor entity ID.

Element
Type
Description
entityId
string

Monitor entity ID.

Response body JSON model

{
  "entityId": "MULTIPROTOCOL_MONITOR-63653CB579F573D1"
}

Related topics