Calculated metrics API - PUT a calculated metric

Updates the specified calculated service metric.

If the calculated service metric with the specified key doesn't exist, a new metric is created.

This request is an Early Adopter release and may be changed in non-compatible way.

PUT
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/calculatedMetrics/service/{metricKey}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/calculatedMetrics/service/{metricKey}

Parameters

Refer to JSON models to find all JSON models that depend on the type of the model.

Parameter Type Description In Required
metricKey string

The key of the calculated service metric to be updated.

The key of the calculated service metric in the body of the request must match this key.

path required
body CalculatedServiceMetric

The JSON body of the request. Contains updated parameters of the calculated service metric.

body optional

The CalculatedServiceMetric object

Descriptor of a calculated service metric.

Element Type Description Required
metadata ConfigurationMetadata

Metadata useful for debugging.

optional
tsmMetricKey string

The key of the calculated service metric.

required
name string

The displayed name of the metric.

required
enabled boolean

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

required
metricDefinition CalculatedMetricDefinition

The source of the metric.

required
unit string

The unit of the metric.

The unit element can hold these values.
required
unitDisplayName string

The display name of the metric's unit.

Only applicable when the unit parameter is set to UNSPECIFIED.

optional
entityId string

Restricts the metric usage to the specified service.

This field is mutually exclusive with the managementZones field.

optional
managementZones string[]

Restricts the metric usage to specified management zones.

This field is mutually exclusive with the entityId field.

optional
conditions Condition[]

The set of conditions for the metric usage.

All the specified conditions must be fulfilled to use the metric.

optional
dimensionDefinition DimensionDefinition

The dimensions splitting of the metric.

optional

The DimensionDefinition object

Parameters of a definition of a calculated service metric.

Element Type Description Required
name string

The name of the dimension.

required
dimension string

The dimension value pattern.

You can define custom placeholders in the placeholders field and use them here.

required
placeholders Placeholder[]

The list of custom placeholders to be used in a dimension value pattern.

optional
topX integer

The number of top values to be calculated.

required
topXDirection string

How to calculate the topX values.

The topXDirection element can hold these values.
required
topXAggregation string

The aggregation of the dimension.

The topXAggregation element can hold these values.
required

The Placeholder object

The custom placeholder to be used as a naming value pattern.

It enables you to extract a request attribute value or other request attribute and use it in the naming pattern.

Element Type Description Required
name string

The name of the placeholder. Use it in the naming pattern as {name}.

required
attribute string

The attribute to extract from. You can only use attributes of the string type.

The attribute element can hold these values.
required
kind string

The type of extraction.

Defines either usage of regular expression (regex) or the position of request attribute value to be extracted. Does not need to be specified if attribute is SERVICE_REQUEST_ATTRIBUTE and aggregation is COUNT.

The kind element can hold these values.
optional
delimiterOrRegex string

Depending on the type value:

  • REGEX_EXTRACTION: The regular expression.
  • BETWEEN_DELIMITER: The opening delimiter string to look for.
  • All other values: The delimiter string to look for.
optional
endDelimiter string

The closing delimiter string to look for.

Required if the kind value is BETWEEN_DELIMITER. Not applicable otherwise.

optional
requestAttribute string

The request attribute to extract from.

Required if the kind value is SERVICE_REQUEST_ATTRIBUTE. Not applicable otherwise.

optional
normalization string

The format of the extracted string.

The normalization element can hold these values.
optional
useFromChildCalls boolean

Only applicable for SERVICE_REQUEST_ATTRIBUTE. If true request attribute will be taken from a child service call.

Defaults to false

optional
aggregation string

Only applicable for SERVICE_REQUEST_ATTRIBUTE when useFromChildCalls is true. When the request attribute occurs across multiple child requests the value may differ. Specify which value should be taken. If COUNT is used, then no kind needs to be specified.

The aggregation element can hold these values.
optional

The Condition object

A condition of a rule usage.

Element Type Description Required
attribute string

The attribute to be matched.

The attribute element can hold these values.
required
comparisonInfo ComparisonInfo

How to match the attribute.

required

The ComparisonInfo object

Type-specific comparison for attributes. The actual set of fields depends on the type of the comparison.

Element Type Description Required
comparison Enum

Operator of the comparision. You can reverse it by setting negate to true.

required
value object

The value to compare to.

optional
negate boolean

Reverse the comparison operator. For example, it turns equals into does not equal.

required
type string

Defines the actual set of fields depending on the value:

STRING -> StringComparisonInfo NUMBER -> NumberComparisonInfo BOOLEAN -> BooleanComparisonInfo HTTP_METHOD -> HttpMethodComparisonInfo STRING_REQUEST_ATTRIBUTE -> StringRequestAttributeComparisonInfo NUMBER_REQUEST_ATTRIBUTE -> NumberRequestAttributeComparisonInfo ZOS_CALL_TYPE -> ZosComparisonInfo IIB_INPUT_NODE_TYPE -> IIBInputNodeTypeComparisonInfo ESB_INPUT_NODE_TYPE -> ESBInputNodeTypeComparisonInfo FAILED_STATE -> FailedStateComparisonInfo FLAW_STATE -> FlawStateComparisonInfo FAILURE_REASON -> FailureReasonComparisonInfo HTTP_STATUS_CLASS -> HttpStatusClassComparisonInfo TAG -> TagComparisonInfo FAST_STRING -> FastStringComparisonInfo SERVICE_TYPE -> ServiceTypeComparisonInfo

The type element can hold these values.
required

The Enum object

The CalculatedMetricDefinition object

The definition of a calculated service metric.

Element Type Description Required
metric string

The metric to be captured.

The metric element can hold these values.
required
requestAttribute string

The request attribute to be captured.

Only applicable when the metric parameter is set to REQUEST_ATTRIBUTE.

optional

The ConfigurationMetadata object

Metadata useful for debugging

Element Type Description Required
clusterVersion string

Dynatrace server version.

optional
configurationVersions integer[]

A Sorted list of the version numbers of the configuration.

optional

Possible values

Possible values for the topXAggregation element in the DimensionDefinition object:

  • AVERAGE
  • COUNT
  • MAX
  • MIN
  • OF_INTEREST_RATIO
  • OTHER_RATIO
  • SINGLE_VALUE
  • SUM

Possible values for the topXDirection element in the DimensionDefinition object:

  • ASCENDING
  • DESCENDING

Possible values for the aggregation element in the Placeholder object:

  • COUNT
  • FIRST
  • LAST

Possible values for the normalization element in the Placeholder object:

  • ORIGINAL
  • TO_LOWER_CASE
  • TO_UPPER_CASE

Possible values for the kind element in the Placeholder object:

  • AFTER_DELIMITER
  • BEFORE_DELIMITER
  • BETWEEN_DELIMITER
  • REGEX_EXTRACTION

Possible values for the type element in the ComparisonInfo object:

  • STRING
  • NUMBER
  • BOOLEAN
  • HTTP_METHOD
  • STRING_REQUEST_ATTRIBUTE
  • NUMBER_REQUEST_ATTRIBUTE
  • ZOS_CALL_TYPE
  • IIB_INPUT_NODE_TYPE
  • ESB_INPUT_NODE_TYPE
  • FAILED_STATE
  • FLAW_STATE
  • FAILURE_REASON
  • HTTP_STATUS_CLASS
  • TAG
  • FAST_STRING
  • SERVICE_TYPE

Possible values for the attribute element in the Condition object:

  • ACTOR_SYSTEM
  • AKKA_ACTOR_CLASS_NAME
  • AKKA_ACTOR_MESSAGE_TYPE
  • AKKA_ACTOR_PATH
  • AZURE_FUNCTIONS_FUNCTION_NAME
  • AZURE_FUNCTIONS_SITE_NAME
  • CICS_PROGRAM_NAME
  • CICS_SYSTEM_ID
  • CICS_TASK_ID
  • CICS_TRANSACTION_ID
  • CPU_TIME
  • CTG_GATEWAY_URL
  • CTG_PROGRAM
  • CTG_SERVER_NAME
  • CTG_TRANSACTION_ID
  • CUSTOMSERVICE_CLASS
  • CUSTOMSERVICE_METHOD
  • DATABASE_CHILD_CALL_COUNT
  • DATABASE_CHILD_CALL_TIME
  • ERROR_COUNT
  • ESB_APPLICATION_NAME
  • ESB_INPUT_TYPE
  • ESB_LIBRARY_NAME
  • ESB_MESSAGE_FLOW_NAME
  • EXCEPTION_CLASS
  • EXCEPTION_MESSAGE
  • FAILED_STATE
  • FAILURE_REASON
  • FLAW_STATE
  • HTTP_REQUEST_METHOD
  • HTTP_STATUS
  • HTTP_STATUS_CLASS
  • IMS_PROGRAM_NAME
  • IMS_TRANSACTION_ID
  • IO_TIME
  • LOCK_TIME
  • MESSAGING_DESTINATION_TYPE
  • MESSAGING_IS_TEMPORARY_QUEUE
  • MESSAGING_QUEUE_NAME
  • MESSAGING_QUEUE_VENDOR
  • NON_DATABASE_CHILD_CALL_COUNT
  • NON_DATABASE_CHILD_CALL_TIME
  • PROCESS_GROUP_NAME
  • PROCESS_GROUP_TAG
  • REMOTE_ENDPOINT
  • REMOTE_METHOD
  • REMOTE_SERVICE_NAME
  • REQUEST_NAME
  • REQUEST_TYPE
  • RESPONSE_TIME
  • RESPONSE_TIME_CLIENT
  • RMI_CLASS
  • RMI_METHOD
  • SERVICE_DISPLAY_NAME
  • SERVICE_NAME
  • SERVICE_PORT
  • SERVICE_PUBLIC_DOMAIN_NAME
  • SERVICE_REQUEST_ATTRIBUTE
  • SERVICE_TAG
  • SERVICE_TYPE
  • SERVICE_WEB_APPLICATION_ID
  • SERVICE_WEB_CONTEXT_ROOT
  • SERVICE_WEB_SERVER_NAME
  • SERVICE_WEB_SERVICE_NAME
  • SERVICE_WEB_SERVICE_NAMESPACE
  • SUSPENSION_TIME
  • TOTAL_PROCESSING_TIME
  • WAIT_TIME
  • WEBREQUEST_QUERY
  • WEBREQUEST_URL
  • WEBREQUEST_URL_HOST
  • WEBREQUEST_URL_PATH
  • WEBREQUEST_URL_PORT
  • WEBSERVICE_ENDPOINT
  • WEBSERVICE_METHOD
  • ZOS_CALL_TYPE

Possible values for the unit element in the CalculatedServiceMetric object:

  • BIT
  • BIT_PER_HOUR
  • BIT_PER_MINUTE
  • BIT_PER_SECOND
  • BYTE
  • BYTE_PER_HOUR
  • BYTE_PER_MINUTE
  • BYTE_PER_SECOND
  • CORES
  • COUNT
  • GIBI_BYTE
  • GIGA_BYTE
  • HOUR
  • KIBI_BYTE
  • KIBI_BYTE_PER_HOUR
  • KIBI_BYTE_PER_MINUTE
  • KIBI_BYTE_PER_SECOND
  • KILO_BYTE
  • KILO_BYTE_PER_HOUR
  • KILO_BYTE_PER_MINUTE
  • KILO_BYTE_PER_SECOND
  • MEBI_BYTE
  • MEBI_BYTE_PER_HOUR
  • MEBI_BYTE_PER_MINUTE
  • MEBI_BYTE_PER_SECOND
  • MEGA_BYTE
  • MEGA_BYTE_PER_HOUR
  • MEGA_BYTE_PER_MINUTE
  • MEGA_BYTE_PER_SECOND
  • MICRO_SECOND
  • MILLI_CORES
  • MILLI_SECOND
  • MILLI_SECOND_PER_MINUTE
  • MINUTE
  • NANO_SECOND
  • NANO_SECOND_PER_MINUTE
  • NOT_APPLICABLE
  • PERCENT
  • PER_HOUR
  • PER_MINUTE
  • PER_SECOND
  • PROMILLE
  • RATIO
  • SECOND
  • STATE
  • UNSPECIFIED

Possible values for the metric element in the CalculatedMetricDefinition object:

  • CPU_TIME
  • DATABASE_CHILD_CALL_COUNT
  • DATABASE_CHILD_CALL_TIME
  • EXCEPTION_COUNT
  • FAILED_REQUEST_COUNT
  • FAILED_REQUEST_COUNT_CLIENT
  • FAILURE_RATE
  • FAILURE_RATE_CLIENT
  • HTTP_4XX_ERROR_COUNT
  • HTTP_4XX_ERROR_COUNT_CLIENT
  • HTTP_5XX_ERROR_COUNT
  • HTTP_5XX_ERROR_COUNT_CLIENT
  • IO_TIME
  • LOCK_TIME
  • NON_DATABASE_CHILD_CALL_COUNT
  • NON_DATABASE_CHILD_CALL_TIME
  • PROCESSING_TIME
  • REQUEST_ATTRIBUTE
  • REQUEST_COUNT
  • RESPONSE_TIME
  • RESPONSE_TIME_CLIENT
  • SUCCESSFUL_REQUEST_COUNT
  • SUCCESSFUL_REQUEST_COUNT_CLIENT
  • WAIT_TIME

Response format

The EntityShortRepresentation object

The short representation of a Dynatrace entity.

Element Type Description
id string

The ID of the Dynatrace entity.

name string

The name of the Dynatrace entity.

description string

A short description of the Dynatrace entity.

Response codes

Code Description
201

Success. The new calculated service metric has been created. Response contains the key of the new metric.

204

Success. The calculated service metric 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.

The request consumes an application/json payload.

This request is an Early Adopter release and may be changed in non-compatible way.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/config/v1/calculatedMetrics/service/{metricKey}/validator
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/config/v1/calculatedMetrics/service/{metricKey}/validator

Response codes

Code 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 modifies the Requests by code calculated service metric created in the POST request example. The request restricts the metric to the Easytravel management zone and adds the condition of process group having the cardVerification tag.

The API token is passed in the Authorization header.

Because the request body is lengthy, it is truncated in this example Curl section. See the full body in the Request body section. You can download or copy the example request body to try it out on your own. Before using it, make sure that you're using management zone and tags that are available in your environment.

The response code of 204 indicates that the update was successful.

Curl

curl -X PUT \
  https://mySampleEnv.live.dynatrace.com/api/config/v1/calculatedMetrics/service/calc:service.requestsbycode \
  -H 'Accept: Accept: application/json; charset=utf-8' \  
  -H 'Authorization: Api-token abcdefjhij1234567890' \  
  -H 'Content-Type: application/json' \  
  -d '{<truncated - see the Request body section >}
'

Request URL

https://mySampleEnv.live.dynatrace.com/api/config/v1/calculatedMetrics/service/calc:service.requestsbycode

Request body

api-examples/config/service/calculated-metric/put.json
Download
{
  "tsmMetricKey": "calc:service.requestsbycode",
  "name": "Requests by code",
  "enabled": true,
  "metricDefinition": {
    "metric": "REQUEST_COUNT",
    "requestAttribute": null
  },
  "unit": "COUNT",
  "unitDisplayName": "",
  "entityId": null,
  "managementZones": [
    "Easytravel"
  ],
  "conditions": [
    {
      "attribute": "PROCESS_GROUP_TAG",
      "comparisonInfo": {
        "type": "TAG",
        "comparison": "TAG_KEY_EQUALS",
        "value": {
          "context": "CONTEXTLESS",
          "key": "payment"
        },
        "negate": false
      }
    },
    {
      "attribute": "PROCESS_GROUP_TAG",
      "comparisonInfo": {
        "type": "TAG",
        "comparison": "TAG_KEY_EQUALS",
        "value": {
          "context": "CONTEXTLESS",
          "key": "cardVerification"
        },
        "negate": false
      }
    }
  ],
  "dimensionDefinition": {
    "name": "HTTP Status class",
    "dimension": "{HTTP-StatusClass}",
    "placeholders": [],
    "topX": 10,
    "topXDirection": "DESCENDING",
    "topXAggregation": "SINGLE_VALUE"
  }
}

Response code

204