• Home
  • Dynatrace API
  • Environment
  • Thresholds
  • PUT a threshold

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.

PUTManagedDynatrace for Governmenthttps://{your-domain}/e/{your-environment-id}/api/v1/thresholds/{thresholdId}
SaaShttps://{your-environment-id}.live.dynatrace.com/api/v1/thresholds/{thresholdId}
Environment ActiveGatehttps://{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

ParameterTypeDescriptionInRequired
thresholdIdstring

The ID of the threshold to create or update.

pathrequired
bodyThresholdRegistrationMessage

JSON body of the request, containing threshold parameters.

bodyoptional

Request body objects

The ThresholdRegistrationMessage object

Parameters of a single plugin or custom event threshold.

ElementTypeDescriptionRequired
thresholdIdstring

The ID of the threshold.

optional
timeseriesIdstring

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
thresholdnumber

The value of the threshold.

optional
alertConditionstring

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

The element can hold these values
  • ABOVE
  • BELOW
optional
samplesinteger

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

optional
violatingSamplesinteger

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

optional
dealertingSamplesinteger

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

optional
eventTypestring

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

The element can hold these values
  • AVAILABILITY_EVENT
  • ERROR_EVENT
  • PERFORMANCE_EVENT
optional
eventNamestring

The name of the event, displayed in the UI.

optional
descriptionstring

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
enabledboolean

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

CodeTypeDescription
201Threshold

Success

Response body objects

The Threshold object

Parameters of a single plugin or custom event threshold.

ElementTypeDescription
thresholdIdstring

The ID of the threshold.

timeseriesIdstring

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.

thresholdnumber

The value of the threshold.

alertConditionstring

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

The element can hold these values
  • ABOVE
  • BELOW
samplesinteger

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

violatingSamplesinteger

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

eventTypestring

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
eventNamestring

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

filterstring

The source of the threshold.

The element can hold these values
  • ALL
  • PLUGIN
  • REMOTE_PLUGIN
  • USER_INTERACTION
enabledboolean

The threshold is enabled/disabled.

dealertingSamplesinteger

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

descriptionstring

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

Related topics
  • Static thresholds for infrastructure monitoring

    Learn about the fixed thresholds used by Dynatrace to determine when a detected slowdown or error-rate increase justifies the generation of a new problem event.