• Home
  • Dynatrace API
  • Configuration
  • Anomaly detection
  • Metric event
  • PUT an event

Metric events anomaly detection API - PUT an event

Updates the specified metric event rule.

The request consumes an application/json payload.

PUTManaged https://{your-domain}/e/{your-environment-id}/api/config/v1/anomalyDetection/metricEvents/{id}
SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/anomalyDetection/metricEvents/{id}
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/anomalyDetection/metricEvents/{id}

Authentication

To execute this request, you need an access token with Write configuration (WriteConfig) scope. To learn how to obtain and use it, see Tokens and authentication.

Parameters

To find all JSON models that depend on the type of the model, refer to JSON models.

ParameterTypeDescriptionInRequired
idstring

The ID of the metric event to be updated.

If you also set the ID in the body, it must match this ID.

pathrequired
bodyMetricEvent

The JSON body of the request. Contains updated parameters of the metric event.

bodyoptional

Request body objects

The MetricEvent object

The configuration of the metric event.

ElementTypeDescriptionRequired
metadataConfigurationMetadata

Metadata useful for debugging

optional
idstring

The ID of the metric event.

optional
metricIdstring

The ID of the metric evaluated by the metric event.

optional
metricSelectorstring

The metric selector that should be executed.

optional
namestring

The name of the metric event displayed in the UI.

required
descriptionstring

The description of the metric event.

required
aggregationTypestring

How the metric data points are aggregated for the evaluation.

The timeseries must support this aggregation.

The element can hold these values
  • AVG
  • COUNT
  • MAX
  • MEDIAN
  • MIN
  • P90
  • SUM
  • VALUE
optional
severitystring

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

The CUSTOM_ALERT type is not correlated with other alerts. The INFO type does not open a problem.

The element can hold these values
  • AVAILABILITY
  • CUSTOM_ALERT
  • ERROR
  • INFO
  • PERFORMANCE
  • RESOURCE_CONTENTION
optional
enabledboolean

The metric event is enabled (true) or disabled (false).

required
disabledReasonstring

The reason of automatic disabling.

The NONE means config was not disabled automatically.

The element can hold these values
  • METRIC_DEFINITION_INCONSISTENCY
  • NONE
  • TOO_MANY_DIMS
  • TOPX_FORCIBLY_DEACTIVATED
optional
warningReasonstring

The reason of a warning set on the config.

The NONE means config has no warnings.

The element can hold these values
  • NONE
  • TOO_MANY_DIMS
optional
alertingScopeMetricEventAlertingScope[]

Defines the scope of the metric event. Only one filter is allowed per filter type, except for tags, where up to 3 are allowed. The filters are combined by conjunction.

optional
metricDimensionsMetricEventDimensions[]

Defines the dimensions of the metric to alert on. The filters are combined by conjunction.

optional
monitoringStrategyMetricEventMonitoringStrategy

A monitoring strategy for a metric event config.

This is the base version of the monitoring strategy, depending on the type, the actual JSON may contain additional fields.

required
primaryDimensionKeystring

Defines which dimension key should be used for the alertingScope.

optional
queryOffsetinteger

Defines the query offset to adapt the evaluation timeframe for known metric latency.

optional

The ConfigurationMetadata object

Metadata useful for debugging

ElementTypeDescriptionRequired
configurationVersionsinteger[]

A sorted list of the version numbers of the configuration.

optional
currentConfigurationVersionsstring[]

A sorted list of version numbers of the configuration.

optional
clusterVersionstring

Dynatrace version.

optional

The MetricEventAlertingScope object

A single filter for the alerting scope.

The actual set of fields depends on type of the filter. Find the list of actual objects in the description of the filterType field or see Metric events anomaly detection API - JSON models.

ElementTypeDescriptionRequired
filterTypestring

Defines the actual set of fields depending on the value. See one of the following objects:

  • ENTITY_ID -> EntityIdAlertingScope
  • MANAGEMENT_ZONE -> ManagementZoneAlertingScope
  • TAG -> TagFilterAlertingScope
  • NAME -> NameAlertingScope
  • CUSTOM_DEVICE_GROUP_NAME -> CustomDeviceGroupNameAlertingScope
  • HOST_GROUP_NAME -> HostGroupNameAlertingScope
  • HOST_NAME -> HostNameAlertingScope
  • PROCESS_GROUP_ID -> ProcessGroupIdAlertingScope
  • PROCESS_GROUP_NAME -> ProcessGroupNameAlertingScope
The element can hold these values
  • CUSTOM_DEVICE_GROUP_NAME
  • ENTITY_ID
  • HOST_GROUP_NAME
  • HOST_NAME
  • MANAGEMENT_ZONE
  • NAME
  • PROCESS_GROUP_ID
  • PROCESS_GROUP_NAME
  • TAG
required

The MetricEventDimensions object

A single filter for the metrics dimensions.

The actual set of fields depends on type of the filter. Find the list of actual objects in the description of the filterType field or see Metric events anomaly detection API - JSON models.

ElementTypeDescriptionRequired
filterTypestring

Defines the actual set of fields depending on the value. See one of the following objects:

  • ENTITY -> MetricEventEntityDimensions
  • STRING -> MetricEventStringDimensions
The element can hold these values
  • ENTITY
  • STRING
required
keystring

The dimensions key on the metric.

optional

The MetricEventMonitoringStrategy object

A monitoring strategy for a metric event config.

This is the base version of the monitoring strategy, depending on the type, the actual JSON may contain additional fields.

ElementTypeDescriptionRequired
typestring

Defines the actual set of fields depending on the value. See one of the following objects:

  • STATIC_THRESHOLD -> MetricEventStaticThresholdMonitoringStrategy
  • AUTO_ADAPTIVE_BASELINE -> MetricEventAutoAdaptiveBaselineMonitoringStrategy
The element can hold these values
  • AUTO_ADAPTIVE_BASELINE
  • STATIC_THRESHOLD
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.

json
{ "metadata": { "configurationVersions": [ 4, 2 ], "clusterVersion": "Mock version" }, "metricId": "com.dynatrace.builtin:host.disk.bytesread", "name": "My metric event", "description": "This is the description for my metric event.", "aggregationType": "AVG", "severity": "CUSTOM_ALERT", "alertingScope": [ { "filterType": "ENTITY_ID", "entityId": "HOST-000000000001E240" }, { "filterType": "TAG", "tagFilter": { "context": "CONTEXTLESS", "key": "someKey", "value": "someValue" } } ], "metricDimensions": [ { "filterType": "ENTITY", "key": "dt.entity.disk", "nameFilter": { "value": "diskName", "operator": "EQUALS" } } ], "enabled": true, "disabledReason": "NONE", "warningReason": "NONE", "monitoringStrategy": { "type": "STATIC_THRESHOLD", "alertCondition": "ABOVE", "samples": 5, "violatingSamples": 3, "dealertingSamples": 5, "threshold": 80, "unit": "KILO_BYTE_PER_SECOND" } }

Response

Response codes

CodeTypeDescription
201EntityShortRepresentation

Success. The new metric event has been created. The response contains the ID of the newly created metric event

204

Success. The metric event has been updated. The response is empty.

400ErrorEnvelope

Failed. The input is invalid.

Response body objects

The EntityShortRepresentation object

The short representation of a Dynatrace entity.

ElementTypeDescription
idstring

The ID of the Dynatrace entity.

namestring

The name of the Dynatrace entity.

descriptionstring

A short description of the Dynatrace entity.

Response body JSON model

json
{ "id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a", "name": "Dynatrace entity", "description": "Dynatrace entity for the REST API example" }

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.

POSTManaged https://{your-domain}/e/{your-environment-id}/api/config/v1/anomalyDetection/metricEvents/{id}/validator
SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/anomalyDetection/metricEvents/{id}/validator
Environment ActiveGate https://{your-activegate-domain}/e/{your-environment-id}/api/config/v1/anomalyDetection/metricEvents/{id}/validator

Authentication

To execute this request, you need an access token with Write configuration (WriteConfig) scope. To learn how to obtain and use it, see Tokens and authentication.

Response

Response codes

CodeTypeDescription
204

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

400ErrorEnvelope

Failed. The input is invalid.

Example

In this example, the request updates the Low disk space rule we created in the POST request example. It changes the threshold to 4% in 9 out of 10 samples. It restricts the scope of the alert to the HOST-IG-1 host, which has the Dynatrace entity ID of HOST-DE7EB04EB33F3040.

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.

Curl

shell
curl -X PUT \ https://mySampleEnv.live.dynatrace.com/api/config/v1/anomalyDetection/metricEvents/1b06b18a-82df-4e18-a4aa-d4543b227734 \ -H 'Authorization: Api-Token dt0c01.abc123.abcdefjhij1234567890' \ -H 'Content-Type: application/json' \ -d '{ "metricId": "com.dynatrace.builtin:host.disk.freespacepercentage", "name": "Low disk space", "description": "The available disk space is below 4%", "aggregationType": "AVG", "eventType": "CUSTOM_ALERT", "alertCondition": "BELOW", "samples": 10, "violatingSamples": 9, "dealertingSamples": 10, "threshold": 4, "entity": "HOST-DE7EB04EB33F3040", "enabled": true, "tagFilters": [] } '

Request URL

plaintext
https://mySampleEnv.live.dynatrace.com/api/config/v1/anomalyDetection/metricEvents/1b06b18a-82df-4e18-a4aa-d4543b227734

Request body

json
{ "metricId": "com.dynatrace.builtin:host.disk.freespacepercentage", "name": "Low disk space", "description": "The available disk space is below 4%", "aggregationType": "AVG", "eventType": "CUSTOM_ALERT", "alertCondition": "BELOW", "samples": 10, "violatingSamples": 9, "dealertingSamples": 10, "threshold": 4, "entity": "HOST-DE7EB04EB33F3040", "enabled": true, "tagFilters": [] }

Response code

204

Result

The updated configuration has the following parameters:

Metric event rule - updated

Related topics
  • Prediction-based anomaly detection

    Read how Dynatrace automatically learns each applications’ unique traffic patterns and is thereby able to forecast the application’s traffic.

  • Problem detection and analysis

    Understand the basic concepts related to how Dynatrace detects and raises alerts for problems detected in your environment.