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.dexp.ae/api/v1/thresholds/{thresholdId}

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

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

Request parameters JSON model

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

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "thresholdId": "tooManyCoffeesMade",
  "timeseriesId": "received.coffees",
  "threshold": 10000,
  "alertCondition": "ABOVE",
  "samples": 1,
  "violatingSamples": 1,
  "dealertingSamples": 1,
  "eventType": "AVAILABILITY_EVENT",
  "eventName": "Too many coffees made",
  "description": "The coffee machine must not produce a number of coffees {alert_condition} {threshold}.\n",
  "enabled": true
}

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

Response parameters JSON model

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.dexp.ae/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.dexp.ae/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