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 | ManagedDynatrace for Government | https://{your-domain}/e/{your-environment-id}/api/v1/thresholds/{thresholdId} |
SaaS | https://{your-environment-id}.live.dynatrace.com/api/v1/thresholds/{thresholdId} | |
Environment ActiveGate | https://{your-activegate-domain}/e/{your-environment-id}/api/v1/thresholds/{thresholdId} |
Authentication
To execute this request, you need an access token with DataExport
scope.
To learn how to obtain and use it, see Tokens and authentication.
Parameters
Parameter | Type | Description | In | Required |
---|---|---|---|---|
thresholdId | string | The ID of the threshold to create or update. | path | required |
body | Threshold | JSON body of the request, containing threshold parameters. | body | optional |
Request body objects
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 | optional |
threshold | number | The value of the threshold. | optional |
alertCondition | string | The condition for the threshold value check: above or below. | 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. | 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 |
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.
{
"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}.",
"enabled": true
}
Response
Response codes
Code | Type | Description |
---|---|---|
201 | Threshold | Success |
Response body objects
The Threshold
object
Parameters of a single plugin or custom event threshold.
Element | Type | Description |
---|---|---|
thresholdId | string | The ID of the threshold. |
timeseriesId | string | The case-sensitive ID of the metric evaluated by threshold. You can use it to find the metric via the |
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. |
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. |
filter | string | The source of the threshold. |
enabled | boolean | The threshold is enabled/disabled. |
dealertingSamples | integer | How many one-minute samples within the evaluation window should go back to normal to close the event. |
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. |
Response body JSON model
{
"thresholdId": "string",
"timeseriesId": "string",
"threshold": 1,
"alertCondition": "ABOVE",
"samples": 1,
"violatingSamples": 1,
"eventType": "APPLICATION_JS_FRAMEWORK_DETECTED",
"eventName": "string",
"filter": "ALL",
"enabled": true,
"dealertingSamples": 1,
"description": "string"
}
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 dt0c01.abc123.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
{
"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