Host anomaly detection API - PUT configuration

Updates the configuration of anomaly detection for hosts.

The request consumes an application/json payload.

PUTSaaShttps://{your-environment-id}.live.dynatrace.com/api/config/v1/anomalyDetection/hosts
Environment ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/anomalyDetection/hosts

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Parameters

Parameter
Type
Description
In
Required
body

The JSON body of the request. Contains parameters of the host anomaly detection configuration.

body
optional

Request body objects

The HostsAnomalyDetectionConfig object

Configuration of anomaly detection for hosts.

Element
Type
Description
Required
connectionLostDetection

Configuration of lost connection detection.

required
diskLowInodesDetection

Configuration of low disk inodes number detection.

required
diskLowSpaceDetection

Configuration of low disk space detection.

required
diskSlowWritesAndReadsDetection

Configuration of slow running disks detection.

required
highCpuSaturationDetection

Configuration of high CPU saturation detection

required
highGcActivityDetection

Configuration of high Garbage Collector activity detection.

required
highMemoryDetection

Configuration of high memory usage detection.

required
highNetworkDetection

Configuration of high network utilization detection.

required
metadata

Metadata useful for debugging

optional
networkDroppedPacketsDetection

Configuration of high number of dropped packets detection.

required
networkErrorsDetection

Configuration of high number of network errors detection.

required
networkHighRetransmissionDetection

Configuration of high retransmission rate detection.

required
networkTcpProblemsDetection

Configuration of TCP connectivity problems detection.

required
outOfMemoryDetection

Configuration of Java out of memory problems detection.

required
outOfThreadsDetection

Configuration of Java out of threads problems detection.

required

The ConnectionLostDetectionConfig object

Configuration of lost connection detection.

Element
Type
Description
Required
enabled
boolean

The detection is enabled (true) or disabled (false).

required
enabledOnGracefulShutdowns
boolean

Alert (true) on graceful host shutdowns.

required

The DiskLowInodesDetectionConfig object

Configuration of low disk inodes number detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for low disk inodes number. If not set, automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The DiskLowInodesThresholds object

Custom thresholds for low disk inodes number. If not set, automatic mode is used.

Element
Type
Description
Required
freeInodesPercentage
integer

Alert if percentage of available inodes is lower than X% in 3 out of 5 samples.

required

The DiskLowSpaceDetectionConfig object

Configuration of low disk space detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for low disk space. If not set, automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The DiskLowSpaceThresholds object

Custom thresholds for low disk space. If not set, automatic mode is used.

Element
Type
Description
Required
freeSpacePercentage
integer

Alert if free disk space is lower than X% in 3 out of 5 samples.

required

The DiskSlowWritesAndReadsDetectionConfig object

Configuration of slow running disks detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for slow running disks. If not set, the automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The DiskSlowWriteAndReadsThresholds object

Custom thresholds for slow running disks. If not set, the automatic mode is used.

Element
Type
Description
Required
writeAndReadTime
integer

Alert if disk read/write time is higher than X milliseconds in 3 out of 5 samples.

required

The HighCpuSaturationDetectionConfig object

Configuration of high CPU saturation detection

Element
Type
Description
Required
customThresholds

Custom thresholds for high CPU saturation. If not set then the automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The HighCpuSaturationThresholds object

Custom thresholds for high CPU saturation. If not set then the automatic mode is used.

Element
Type
Description
Required
cpuSaturation
integer

Alert if CPU usage is higher than X% in 3 out of 5 samples.

required

The HighGcActivityDetectionConfig object

Configuration of high Garbage Collector activity detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for high GC activity. If not set, automatic mode is used.

Meeting any of these conditions triggers an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The HighGcActivityThresholds object

Custom thresholds for high GC activity. If not set, automatic mode is used.

Meeting any of these conditions triggers an alert.

Element
Type
Description
Required
gcSuspensionPercentage
integer

GC suspension is higher than X% in 3 out of 5 samples.

required
gcTimePercentage
integer

GC time is higher than X% in 3 out of 5 samples.

required

The HighMemoryDetectionConfig object

Configuration of high memory usage detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for high memory usage. If not set then the automatic mode is used.

Both conditions must be met to trigger an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The HighMemoryThresholds object

Custom thresholds for high memory usage. If not set then the automatic mode is used.

Both conditions must be met to trigger an alert.

Element
Type
Description
Required
pageFaultsPerSecondNonWindows
integer

Memory page fault rate is higher than X faults per second on Linux.

required
pageFaultsPerSecondWindows
integer

Memory page fault rate is higher than X faults per second on Windows.

required
usedMemoryPercentageNonWindows
integer

Memory usage is higher than X% on Linux.

required
usedMemoryPercentageWindows
integer

Memory usage is higher than X% on Windows.

required

The HighNetworkDetectionConfig object

Configuration of high network utilization detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for high network utilization. If not set, automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The HighNetworkThresholds object

Custom thresholds for high network utilization. If not set, automatic mode is used.

Element
Type
Description
Required
utilizationPercentage
integer

Alert if sent/received traffic utilization is higher than X% in 3 out of 5 samples.

required

The ConfigurationMetadata object

Metadata useful for debugging

Element
Type
Description
Required
clusterVersion
string

Dynatrace version.

optional
configurationVersions
integer[]

A sorted list of the version numbers of the configuration.

optional
currentConfigurationVersions
string[]

A sorted list of version numbers of the configuration.

optional

The NetworkDroppedPacketsDetectionConfig object

Configuration of high number of dropped packets detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for dropped packets. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The NetworkDroppedPacketsThresholds object

Custom thresholds for dropped packets. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

Element
Type
Description
Required
droppedPacketsPercentage
integer

Receive/transmit dropped packet percentage is higher than X% in 3 out of 5 samples.

required
totalPacketsRate
integer

Total receive/transmit packets rate is higher than X packets per second in 3 out of 5 samples.

required

The NetworkErrorsDetectionConfig object

Configuration of high number of network errors detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for network errors. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The NetworkErrorsThresholds object

Custom thresholds for network errors. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

Element
Type
Description
Required
errorsPercentage
integer

Receive/transmit error packet percentage is higher than X% in 3 out of 5 samples.

required
totalPacketsRate
integer

Total receive/transmit packets rate is higher than X packets per second in 3 out of 5 samples.

required

The NetworkHighRetransmissionDetectionConfig object

Configuration of high retransmission rate detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for high retransmission rate. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The NetworkHighRetransmissionThresholds object

Custom thresholds for high retransmission rate. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

Element
Type
Description
Required
retransmissionRatePercentage
integer

Retransmission rate is higher than X% in 3 out of 5 samples.

required
retransmittedPacketsNumberPerMinute
integer

Number of retransmitted packets is higher than X packets per minute in 3 out of 5 samples.

required

The NetworkTcpProblemsDetectionConfig object

Configuration of TCP connectivity problems detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for TCP connection problems. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The NetworkTcpProblemsThresholds object

Custom thresholds for TCP connection problems. If not set, automatic mode is used.

All of these conditions must be met to trigger an alert.

Element
Type
Description
Required
failedConnectionsNumberPerMinute
integer

Number of failed connections is higher than X connections per minute in 3 out of 5 samples.

required
newConnectionFailuresPercentage
integer

Percentage of new connection failures is higher than X% in 3 out of 5 samples.

required

The OutOfMemoryDetectionConfig object

Configuration of Java out of memory problems detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for Java out of memory. If not set, automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The OutOfMemoryThresholds object

Custom thresholds for Java out of memory. If not set, automatic mode is used.

Element
Type
Description
Required
outOfMemoryExceptionsNumber
integer

Alert if the number of Java out of memory exceptions is X per minute or higher.

required

The OutOfThreadsDetectionConfig object

Configuration of Java out of threads problems detection.

Element
Type
Description
Required
customThresholds

Custom thresholds for Java out of threads detection. If not set, automatic mode is used.

optional
enabled
boolean

The detection is enabled (true) or disabled (false).

required

The OutOfThreadsThresholds object

Custom thresholds for Java out of threads detection. If not set, automatic mode is used.

Element
Type
Description
Required
outOfThreadsExceptionsNumber
integer

Alert if the number of Java out of threads exceptions is X per minute or higher.

required

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.

{
"connectionLostDetection": {
"enabled": true,
"enabledOnGracefulShutdowns": true
},
"diskLowInodesDetection": {
"customThresholds": {
"freeInodesPercentage": 10
},
"enabled": true
},
"diskLowSpaceDetection": {
"customThresholds": {
"freeSpacePercentage": 10
},
"enabled": true
},
"diskSlowWritesAndReadsDetection": {
"customThresholds": {
"writeAndReadTime": 300
},
"enabled": true
},
"highCpuSaturationDetection": {
"customThresholds": {
"cpuSaturation": 90
},
"enabled": true
},
"highGcActivityDetection": {
"customThresholds": {
"gcSuspensionPercentage": 20,
"gcTimePercentage": 35
},
"enabled": true
},
"highMemoryDetection": {
"customThresholds": {
"pageFaultsPerSecondNonWindows": 10,
"pageFaultsPerSecondWindows": 50,
"usedMemoryPercentageNonWindows": 85,
"usedMemoryPercentageWindows": 85
},
"enabled": true
},
"highNetworkDetection": {
"customThresholds": {
"utilizationPercentage": 88
},
"enabled": true
},
"metadata": {
"clusterVersion": "Mock version",
"configurationVersions": [
4,
2
]
},
"networkDroppedPacketsDetection": {
"customThresholds": {
"droppedPacketsPercentage": 8,
"totalPacketsRate": 8
},
"enabled": true
},
"networkErrorsDetection": {
"customThresholds": {
"errorsPercentage": 9,
"totalPacketsRate": 9
},
"enabled": true
},
"networkHighRetransmissionDetection": {
"customThresholds": {
"retransmissionRatePercentage": 15,
"retransmittedPacketsNumberPerMinute": 15
},
"enabled": true
},
"networkTcpProblemsDetection": {
"customThresholds": {
"failedConnectionsNumberPerMinute": 5,
"newConnectionFailuresPercentage": 5
},
"enabled": true
},
"outOfMemoryDetection": {
"customThresholds": {
"outOfMemoryExceptionsNumber": 2
},
"enabled": true
},
"outOfThreadsDetection": {
"customThresholds": {
"outOfThreadsExceptionsNumber": 2
},
"enabled": true
}
}

Response

Response codes

Code
Type
Description
204
-

Success. Configuration has been updated. Response doesn't have a body.

400

Failed. The input is invalid

Validate payload

We recommend that you validate the payload before submitting it with an actual request. A response code of 204 indicates a valid payload.

The request consumes an application/json payload.

POSTSaaShttps://{your-environment-id}.live.dynatrace.com/api/config/v1/anomalyDetection/hosts/validator
Environment ActiveGatehttps://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/anomalyDetection/hosts/validator

Authentication

To execute this request, you need an access token with WriteConfig scope.

To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

Code
Type
Description
204
-

Validated. The submitted configuration is valid. Response doesn't have a body.

400

Failed. The input is invalid

Example

In this example, the request updates the configuration of anomaly detection for database services from the GET request example. It activates the Alert on graceful host shutdowns feature. It also changes Detect CPU saturation on host mode to based on custom settings and sets the following threshold:

  • Alert if CPU usage is higher than 90% in 3 out of 5 samples.

The API token is passed in the Authorization header.

You can download or copy the example request body to try it out on your own. First, be sure to create a backup copy of your current configuration with the GET host anomaly detection configuration call.

Curl

curl -X PUT \
https://mySampleEnv.live.dynatrace.com/api/config/v1/anomalyDetection/hosts \
-H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \
-H 'Content-Type: application/json' \
-d '{<truncated - see the Request body section below>}'

Request URL

https://mySampleEnv.live.dynatrace.com/api/config/v1/anomalyDetection/hosts

Request body

{
"connectionLostDetection": {
"enabled": true,
"enabledOnGracefulShutdowns": true
},
"highCpuSaturationDetection": {
"enabled": true,
"customThresholds": {
"cpuSaturation": 90
}
},
"highMemoryDetection": {
"enabled": true
},
"highGcActivityDetection": {
"enabled": true
},
"outOfMemoryDetection": {
"enabled": true
},
"outOfThreadsDetection": {
"enabled": true
},
"networkDroppedPacketsDetection": {
"enabled": true
},
"networkErrorsDetection": {
"enabled": true
},
"highNetworkDetection": {
"enabled": true
},
"networkTcpProblemsDetection": {
"enabled": true
},
"networkHighRetransmissionDetection": {
"enabled": true
},
"diskLowSpaceDetection": {
"enabled": true
},
"diskSlowWritesAndReadsDetection": {
"enabled": true
},
"diskLowInodesDetection": {
"enabled": true
}
}

Response code

204

Result

The updated configuration has the following parameters:

Anomaly detection config - hosts - updated