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	ThresholdRegistrationMessage	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 `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 element can hold these values `ABOVE` `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. The element can hold these values `AVAILABILITY_EVENT` `ERROR_EVENT` `PERFORMANCE_EVENT`	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.

json
{
  "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 `timeseries` endpoint of the API.
threshold	number	The value of the threshold.
alertCondition	string	The condition for the threshold value check: above or below. The element can hold these values `ABOVE` `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. The element can hold these values `APPLICATION_JS_FRAMEWORK_DETECTED` `APPLICATION_OVERLOAD_PREVENTION` `AVAILABILITY_EVENT` `CONNECTION_LOST` `CPU_SATURATED` `CUSTOM_ALERT` `CUSTOM_ANNOTATION` `CUSTOM_APPLICATION_OVERLOAD_PREVENTION` `CUSTOM_APP_CRASH_RATE_INCREASED` `CUSTOM_CONFIGURATION` `CUSTOM_DEPLOYMENT` `CUSTOM_INFO` `DATABASE_CONNECTION_FAILURE` `DEPLOYMENT_CHANGED_CHANGE` `DEPLOYMENT_CHANGED_NEW` `DEPLOYMENT_CHANGED_REMOVED` `DYNATRACE_INTERNAL` `EBS_VOLUME_HIGH_LATENCY` `ELASTIC_LOAD_BALANCER_HIGH_BACKEND_FAILURE_RATE` `ELASTIC_LOAD_BALANCER_HIGH_FAILURE_RATE` `ELASTIC_LOAD_BALANCER_HIGH_UNHEALTHY_HOST_RATE` `ERROR_EVENT` `ESXI_HOST_VM_MOTION_ARRIVED` `ESXI_HOST_VM_MOTION_LEFT` `ESXI_HOST_VM_STARTED` `ESXI_START` `ESXI_VM_DISCONNECTED` `ESXI_VM_MOTION` `ESXI_VM_POWER_OFF` `ESXI_VM_START` `FAILURE_RATE_INCREASED` `HIGH_CONNECTIVITY_FAILURES` `HIGH_DROPPED_PACKETS_RATE` `HIGH_GC_ACTIVITY` `HIGH_LATENCY` `HIGH_NETWORK_ERROR_RATE` `HIGH_NETWORK_LOSS_RATE` `HIGH_NETWORK_UTILIZATION` `HOST_CONNECTION_FAILED` `HOST_CONNECTION_LOST` `HOST_DATASTORE_LOW_DISK_SPACE` `HOST_DISK_LOW_INODES` `HOST_GRACEFULLY_SHUTDOWN` `HOST_LOG_AVAILABILITY` `HOST_LOG_ERROR` `HOST_LOG_MATCHED` `HOST_LOG_PERFORMANCE` `HOST_MAINTENANCE` `HOST_NO_CONNECTION` `HOST_OF_SERVICE_UNAVAILABLE` `HOST_SHUTDOWN` `HOST_TIMEOUT` `HTTP_CHECK_GLOBAL_OUTAGE` `HTTP_CHECK_LOCAL_OUTAGE` `HTTP_CHECK_TEST_LOCATION_SLOWDOWN` `INSUFFICIENT_DISK_QUEUE_DEPTH` `JAVASCRIPT_ERROR_RATE_INCREASED` `LAMBDA_FUNCTION_HIGH_ERROR_RATE` `LOG_AVAILABILITY` `LOG_ERROR` `LOG_MATCHED` `LOG_PERFORMANCE` `LOW_DISK_SPACE` `LOW_STORAGE_SPACE` `MARKED_FOR_TERMINATION` `MEMORY_RESOURCES_EXHAUSTED` `MEMORY_SATURATED` `MOBILE_APPLICATION_OVERLOAD_PREVENTION` `MOBILE_APP_CRASH_RATE_INCREASED` `MONITORING_UNAVAILABLE` `OPENSTACK_HOST_VM_SHUTDOWN` `OPENSTACK_HOST_VM_STARTED` `OPENSTACK_KEYSTONE_SLOW` `OPENSTACK_KEYSTONE_UNHEALTHY` `OPENSTACK_VM_LAUNCH_FAILED` `OPENSTACK_VM_MOTION` `OSI_DOCKER_DEVICEMAPPER_LOW_DATA_SPACE` `OSI_DOCKER_DEVICEMAPPER_LOW_METADATA_SPACE` `OVERLOADED_STORAGE` `PERFORMANCE_EVENT` `PGI_CRASHED_INFO` `PGI_HAPROXY_QUEUED_REQUESTS_HIGH` `PGI_HAPROXY_SESSION_USAGE_HIGH` `PGI_LOG_MATCHED` `PGI_MEMDUMP` `PGI_MYSQL_SLOW_QUERIES_RATE_HIGH` `PGI_OF_SERVICE_UNAVAILABLE` `PGI_RMQ_HIGH_FILE_DESC_USAGE` `PGI_RMQ_HIGH_MEM_USAGE` `PGI_RMQ_HIGH_PROCESS_USAGE` `PGI_RMQ_HIGH_SOCKETS_USAGE` `PGI_RMQ_LOW_DISK_SPACE` `PROCESS_CRASHED` `PROCESS_CUSTOM_AVAILABILITY` `PROCESS_CUSTOM_ERROR` `PROCESS_CUSTOM_PERFORMANCE` `PROCESS_GROUP_LOW_INSTANCE_COUNT` `PROCESS_LOG_AVAILABILITY` `PROCESS_LOG_ERROR` `PROCESS_LOG_PERFORMANCE` `PROCESS_RESTART` `PROCESS_UNAVAILABLE` `RDS_AZ_FAILOVER_COMPLETED` `RDS_AZ_FAILOVER_STARTED` `RDS_BACKUP_COMPLETED` `RDS_BACKUP_STARTED` `RDS_OF_SERVICE_UNAVAILABLE` `RDS_RESTART` `RDS_RESTART_SEQUENCE` `RESOURCE_CONTENTION` `SERVICE_RESPONSE_TIME_DEGRADED` `SLOW_DISK` `SYNTHETIC_AVAILABILITY` `SYNTHETIC_NODE_OUTAGE` `SYNTHETIC_PRIVATE_LOCATION_OUTAGE` `SYNTHETIC_SLOWDOWN` `THREADS_RESOURCES_EXHAUSTED` `UNEXPECTED_HIGH_LOAD` `UNEXPECTED_LOW_LOAD` `USER_ACTION_DURATION_DEGRADATION` `VIRTUAL_MACHINE_SHUTDOWN` `WEB_CHECK_GLOBAL_OUTAGE` `WEB_CHECK_LOCAL_OUTAGE`
eventName	string	The name of the event to trigger on the threshold violation.
filter	string	The source of the threshold. The element can hold these values `ALL` `PLUGIN` `REMOTE_PLUGIN` `USER_INTERACTION`
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

json
{
  "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

bash
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

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

Request body

json
{
  "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

json
{
  "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