Thresholds API - PUT a threshold

Creates or updates an existing threshold for a plugin or a custom event.

The request consumes and produces an application/json payload.

PUT
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/thresholds/{thresholdId}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/thresholds/{thresholdId}

Parameters

Parameter Type Description In Required
thresholdId string

The ID of the threshold to create or update.

path required
body ThresholdRegistrationMessage

JSON body of the request, containing threshold parameters.

body optional

The ThresholdRegistrationMessage object

Parameters of a single plugin or custom event threshold.

Element Type Description Required
thresholdId string

The ID of the threshold.

optional
timeseriesId string

The case-sensitive ID of the metric evaluated by threshold.

You can find metric IDs, by performing the GET request to the timeseries endpoint of the API.

optional
threshold number

The value of the threshold.

optional
alertCondition string

The condition for the threshold value check: above or below.

The alertCondition element can hold these values.
optional
samples integer

The number of one-minute samples to form the sliding evaluation window.

optional
violatingSamples integer

How many one-minute samples within the evaluation window should violate the threshold to trigger an event.

optional
dealertingSamples integer

How many one-minute samples within the evaluation window should go back to normal to close the event.

optional
eventType string

The type of the event to trigger on the threshold violation.

The eventType element can hold these values.
optional
eventName string

The name of the event, displayed in the UI.

optional
description string

A description of the event, triggered by a threshold violation.

You can use the following placeholders: {severity}: the actual metric value, {alert_condition}: above or below threshold condition, {threshold}: the threshold value,{violating_samples}: the number of samples, violating the threshold, {dimensions}: metric's dimension that violated the threshold.

optional
enabled boolean

The threshold is enabled/disabled.

optional

Possible values

Possible values for the eventType element in the ThresholdRegistrationMessage object:

  • AVAILABILITY_EVENT
  • ERROR_EVENT
  • PERFORMANCE_EVENT

Possible values for the alertCondition element in the ThresholdRegistrationMessage object:

  • ABOVE
  • BELOW

Response format

The Threshold object

Parameters of a single plugin or custom event threshold.

Element Type Description
thresholdId string

The ID of the threshold.

threshold number

The value of the threshold.

alertCondition string

The condition for the threshold value check: above or below.

samples integer

The number of one-minute samples that form sliding evaluation window.

violatingSamples integer

How many one-minute samples within the evaluation window should violate the threshold to trigger an event.

dealertingSamples integer

How many one-minute samples within the evaluation window should go back to normal to close the event.

eventType string

The type of the event to trigger on the threshold violation.

eventName string

The name of the event to trigger on the threshold violation.

description string

A description of the event, triggered by a threshold violation.

You can use the following placeholders: {severity}: the actual metric value, {alert_condition}: above or below threshold condition, {threshold}: the threshold value,{violating_samples}: the number of samples, violating the threshold, {dimensions}: metric's dimension that violated the threshold.

enabled boolean

The threshold is enabled/disabled.

timeseriesId string

The case-sensitive ID of the metric evaluated by threshold.

You can use it to find the metric via the timeseries endpoint of the API.

filter string

The source of the threshold.

Example

In this example, the request creates a new mqMemoryUsage threshold. This threshold evaluates 10 samples; and if 3 of them violate a threshold of 75%, the performance event is triggered. The event is closed when 5 out of 10 samples are back below the threshold.

The API token is passed in the Authorization header.

The request returns parameters of the newly created threshold as confirmation.

Curl

curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/v1/thresholds/mqMemoryUsage \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \  
  -H 'Content-Type: application/json' \  
  -d '{
  "timeseriesId": "ruxit.python.rabbitmq:mem_usage",
  "threshold": 75,
  "alertCondition": "ABOVE",
  "samples": 10,
  "violatingSamples": 3,
  "dealertingSamples": 5,
  "eventType": "PERFORMANCE_EVENT",
  "eventName": "MQ memory usage is above 75%",
  "description": "Memory usage in RabbitMQ is exceeding {threshold}%.",
  "enabled": true
}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/v1/thresholds/mqMemoryUsage

Request body

api-examples/env/threshold/put-a-threshold.json
Download
{
  "timeseriesId": "ruxit.python.rabbitmq:mem_usage",
  "threshold": 75,
  "alertCondition": "ABOVE",
  "samples": 10,
  "violatingSamples": 3,
  "dealertingSamples": 5,
  "eventType": "PERFORMANCE_EVENT",
  "eventName": "MQ memory usage is above 75%",
  "description": "Memory usage in RabbitMQ is exceeding {threshold}%.",
  "enabled": true
}

Response body

{
  "thresholdId": "mqMemoryUsage",
  "threshold": 75,
  "alertCondition": "ABOVE",
  "samples": 10,
  "violatingSamples": 3,
  "eventType": "PERFORMANCE_EVENT",
  "eventName": "MQ memory usage is above 75%",
  "filter": "USER_INTERACTION",
  "enabled": true,
  "dealertingSamples": 5,
  "description": "Memory usage in RabbitMQ is exceeding {threshold}%.",
  "timeseriesId": "ruxit.python.rabbitmq:mem_usage"
}

Response code

201