Service metrics API - POST a metric

Creates a new calculated service metric.

The body must not provide an ID. An ID is assigned automatically by the Dynatrace server.

The request consumes and produces an application/json payload.

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

Authentication

To execute this request, you need the Write configuration (WriteConfig) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

Parameters

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

Parameter Type Description In Required
body CalculatedServiceMetric

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

body optional

The CalculatedServiceMetric object

Descriptor of a calculated service metric.

Element Type Description Required
metadata ConfigurationMetadata 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 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 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.

When the attribute is SERVICE_REQUEST_ATTRIBUTE attribute and aggregation is COUNT, needs to be set to ORIGINAL_TEXT

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.
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

If true request attribute will be taken from a child service call.

Only applicable for the SERVICE_REQUEST_ATTRIBUTE attribute. Defaults to false.

optional
aggregation string

Which value of the request attribute must be used when it occurs across multiple child requests.

Only applicable for the SERVICE_REQUEST_ATTRIBUTE attribute, when useFromChildCalls is true.

For the COUNT aggregation, the kind field is not applicable.

The aggregation element can hold these values.
optional
source PropagationSource optional

The PropagationSource object

Defines valid sources of request attributes for conditions or placeholders.

Element Type Description Required
managementZone string

Use only request attributes from services that belong to this management zone.. Use either this or serviceTag

optional
serviceTag UniversalTag optional

The UniversalTag object

Use only request attributes from services that have this tag. Use either this or managementZone

Element Type Description Required
tagKey UniversalTagKey optional
value string

The value of the tag. Not applicable to custom tags.

If a tag does have a separate key and value (in the textual representation they are split by the colon ‘:’), this field is set with the actual value. Key-value pairs can occur for automatically imported tags and tags set by rules if extractors are used.

optional
key string

The key of the tag. For custom tags, put the tag value here.

The key allows categorization of multiple tags. It is possible that there are multiple values for a single key which will all be represented as standalone tags. Therefore, the key does not have the semantic of a map key but is more like a key of a key-value tuple. In some cases, for example custom tags, the key represents the actual tag value and the value field is not set – those are called valueless tags.

required
context string

The origin of the tag, such as AWS or Cloud Foundry. For custom tags use the CONTEXTLESS value.

The context is set for tags that are automatically imported by OneAgent (for example, from the AWS console or environment variables). It’s useful for determining the origin of tags when not manually defined, and it also helps to prevent clashes with other existing tags. If the tag is not automatically imported, CONTEXTLESS set.

The context element can hold these values.
optional

The UniversalTagKey object

Element Type Description Required
context string The context element can hold these values. optional
key string 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 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 object

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. See one of the following objects:

  • 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 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
currentConfigurationVersions string[]

A Sorted list of string version numbers of the configuration.

optional
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 context element in the UniversalTagKey object:

  • AWS
  • AWS_GENERIC
  • AZURE
  • CLOUD_FOUNDRY
  • CONTEXTLESS
  • ENVIRONMENT
  • GOOGLE_COMPUTE_ENGINE
  • KUBERNETES

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
  • ORIGINAL_TEXT
  • REGEX_EXTRACTION

Possible values for the type element in the ComparisonInfo object:

  • BOOLEAN
  • ESB_INPUT_NODE_TYPE
  • FAILED_STATE
  • FAILURE_REASON
  • FAST_STRING
  • FLAW_STATE
  • HTTP_METHOD
  • HTTP_STATUS_CLASS
  • IIB_INPUT_NODE_TYPE
  • NUMBER
  • NUMBER_REQUEST_ATTRIBUTE
  • SERVICE_TYPE
  • STRING
  • STRING_REQUEST_ATTRIBUTE
  • TAG
  • ZOS_CALL_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
  • DISK_IO_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
  • LAMBDA_COLDSTART
  • LOCK_TIME
  • MESSAGING_DESTINATION_TYPE
  • MESSAGING_IS_TEMPORARY_QUEUE
  • MESSAGING_QUEUE_NAME
  • MESSAGING_QUEUE_VENDOR
  • NETWORK_IO_TIME
  • 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_RELATIVE_URL
  • 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
  • DAY
  • DECIBEL_MILLI_WATT
  • GIBI_BYTE
  • GIGA
  • GIGA_BYTE
  • HOUR
  • KIBI_BYTE
  • KIBI_BYTE_PER_HOUR
  • KIBI_BYTE_PER_MINUTE
  • KIBI_BYTE_PER_SECOND
  • KILO
  • 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
  • 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
  • MONTH
  • NANO_SECOND
  • NANO_SECOND_PER_MINUTE
  • NOT_APPLICABLE
  • PERCENT
  • PER_HOUR
  • PER_MINUTE
  • PER_SECOND
  • PIXEL
  • PROMILLE
  • RATIO
  • SECOND
  • STATE
  • UNSPECIFIED
  • WEEK
  • YEAR

Possible values for the metric element in the CalculatedMetricDefinition object:

  • CPU_TIME
  • DATABASE_CHILD_CALL_COUNT
  • DATABASE_CHILD_CALL_TIME
  • DISK_IO_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
  • NETWORK_IO_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.

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.

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

Authentication

To execute this request, you need the Write configuration (WriteConfig) permission assigned to your API token. To learn how to obtain and use it, see Tokens and authentication.

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 creates a calculated service metric that tracks the number of requests in services tagged with the payment tag. It splits the values by HTTP status class.

The metric key is calc:service.requestsbycode and the display name is Requests by code.

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 a tag that is available in your environment.

The response contains the key and the name of the newly created metric.

Curl

curl -X POST \
  https://mySampleEnv.live.dynatrace.com/api/config/v1/calculatedMetrics/service \
  -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

Request body

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

Response body

{
  "id": "calc:service.requestsbycode",
  "name": "Requests by code"
}

Response code

201