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 ID of the calculated service metric to update.

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

path required
body ServiceMetric

JSON body of the request containing updated definition of the calculated service metric.

body optional

The ServiceMetric object

Element Type Description Required
metadata ConfigurationMetadata

Metadata useful for debugging.

optional
tsmMetricKey string

A unique metric key.

required
name string

The name of this calculated service metric.

required
enabled boolean

Calculated service metric enabled/disabled.

required
metricDefinition MetricDefinition

Metric source.

required
unit string

Metric unit.

The unit element can hold these values.
required
unitDisplayName string

The unit display name, if unit is unspecified.

optional
entityId string

Specifies the service entity id for which this metric should be created.

optional
managementZones string[]

Specifies the management zones for which this metric should be created.

optional
conditions Condition[]

Specifies the conditions a request must fulfill for the calculated service metric to be created.

optional
dimensionDefinition DimensionDefinition

Specifies the optional dimension.

optional

The DimensionDefinition object

Element Type Description Required
name string

The name of this dimension.

required
dimension string

The dimension of this metric.

required
placeholders Placeholder[]

The list of extractions to be inserted into the dimension.

optional
topX integer

The number of top values to be calculated.

required
topXDirection string

How the topX need to be calculated.

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 in the request rule naming pattern.

It enables you to extract a request attribute value or other request attribute and use it in the request 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.

The kind element can hold these values.
required
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.
required
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

The Condition object

A condition for the request naming 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 information 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 the begin with into does not begin with.

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 FAILED_STATE -> FailedStateComparisonInfo FLAW_STATE -> FlawStateComparisonInfo FAILURE_REASON -> FailureReasonComparisonInfo HTTP_STATUS_CLASS -> HttpStatusClassComparisonInfo TAG -> TagComparisonInfo FAST_STRING -> FastStringComparisonInfo

The type element can hold these values.
required

The Enum object

The MetricDefinition object

Element Type Description Required
metric string

Service metric to be captured.

The metric element can hold these values.
required
requestAttribute string

The request attribute this metric should capture.

optional

The ConfigurationMetadata object

Metadata useful for debugging

Element Type Description Required
configurationVersions integer[]

A Sorted list of the version numbers of the configuration.

optional
clusterVersion string

Dynatrace server version.

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 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
  • FAILED_STATE
  • FLAW_STATE
  • FAILURE_REASON
  • HTTP_STATUS_CLASS
  • TAG
  • FAST_STRING

Possible values for the attribute element in the Condition object:

  • AKKA_ACTOR_CLASS_NAME
  • AKKA_ACTOR_MESSAGE_TYPE
  • AKKA_ACTOR_PATH
  • CICS_PROGRAM_NAME
  • CICS_SYSTEM_ID
  • CICS_TASK_ID
  • CICS_TRANSACTION_ID
  • CPU_TIME
  • CTG_PROGRAM
  • CTG_TRANSACTION_ID
  • CUSTOMSERVICE_CLASS
  • CUSTOMSERVICE_METHOD
  • DATABASE_CHILD_CALL_COUNT
  • DATABASE_CHILD_CALL_TIME
  • ERROR_COUNT
  • EXCEPTION_CLASS
  • EXCEPTION_MESSAGE
  • FAILED_STATE
  • FAILURE_REASON
  • FLAW_STATE
  • HTTP_REQUEST_METHOD
  • HTTP_STATUS
  • HTTP_STATUS_CLASS
  • IIB_APPLICATION_NAME
  • IIB_INPUT_TYPE
  • IIB_LIBRARY_NAME
  • IIB_MESSAGE_FLOW_NAME
  • 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_TAG
  • REMOTE_ENDPOINT
  • REMOTE_METHOD
  • 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_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 ServiceMetric 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 MetricDefinition 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. Calculated service metric has been created. Response contains its ID and name.

204

Success. 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 does not 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