Service metrics API - GET a metric

Gets the descriptor of the specified calculated service metric.

The request produces an application/json payload.

GET	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}

Authentication

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

Parameters

Parameter	Type	Description	In	Required
metricKey	string	The key of the required calculated service metric.	path	required

Response format

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

Response parameters JSON model

The CalculatedServiceMetric object

Descriptor of a calculated service metric.

Element	Type	Description
metadata	ConfigurationMetadata
tsmMetricKey	string	The key of the calculated service metric.
name	string	The displayed name of the metric.
enabled	boolean	The metric is enabled (`true`) or disabled (`false`).
metricDefinition	CalculatedMetricDefinition
unit	string	The unit of the metric. The unit element can hold these values.
unitDisplayName	string	The display name of the metric's unit. Only applicable when the unit parameter is set to `UNSPECIFIED`.
entityId	string	Restricts the metric usage to the specified service. This field is mutually exclusive with the managementZones field.
managementZones	string[]	Restricts the metric usage to specified management zones. This field is mutually exclusive with the entityId field.
conditions	Condition[]	The set of conditions for the metric usage. All the specified conditions must be fulfilled to use the metric.
dimensionDefinition	DimensionDefinition

The DimensionDefinition object

Parameters of a definition of a calculated service metric.

Element	Type	Description
name	string	The name of the dimension.
dimension	string	The dimension value pattern. You can define custom placeholders in the placeholders field and use them here.
placeholders	Placeholder[]	The list of custom placeholders to be used in a dimension value pattern.
topX	integer	The number of top values to be calculated.
topXDirection	string	How to calculate the topX values. The topXDirection element can hold these values.
topXAggregation	string	The aggregation of the dimension. The topXAggregation element can hold these values.

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
name	string	The name of the placeholder. Use it in the naming pattern as `{name}`.
attribute	string	The attribute to extract from. You can only use attributes of the string type. The attribute element can hold these values.
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.
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.
endDelimiter	string	The closing delimiter string to look for. Required if the kind value is `BETWEEN_DELIMITER`. Not applicable otherwise.
requestAttribute	string	The request attribute to extract from. Required if the kind value is `SERVICE_REQUEST_ATTRIBUTE`. Not applicable otherwise.
normalization	string	The format of the extracted string. The normalization element can hold these values.
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`.
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.
source	PropagationSource

The PropagationSource object

Defines valid sources of request attributes for conditions or placeholders.

Element	Type	Description
managementZone	string	Use only request attributes from services that belong to this management zone.. Use either this or `serviceTag`
serviceTag	UniversalTag

The UniversalTag object

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

Element	Type	Description
tagKey	UniversalTagKey
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.
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.
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.

The UniversalTagKey object

Element	Type	Description
context	string	The context element can hold these values.
key	string

The Condition object

A condition of a rule usage.

Element	Type	Description
attribute	string	The attribute to be matched. The attribute element can hold these values.
comparisonInfo	ComparisonInfo

The ComparisonInfo object

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

Element	Type	Description
comparison	object	Operator of the comparision. You can reverse it by setting negate to `true`.
value	object	The value to compare to.
negate	boolean	Reverse the comparison operator. For example, it turns equals into does not equal.
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.

The CalculatedMetricDefinition object

The definition of a calculated service metric.

Element Type Description

metric

string

Element	Type	Description
metric	string	The metric to be captured. The metric element can hold these values.
requestAttribute	string	The request attribute to be captured. Only applicable when the metric parameter is set to `REQUEST_ATTRIBUTE`.

The metric to be captured.

The metric element can hold these values.

requestAttribute

string

The request attribute to be captured.

Only applicable when the metric parameter is set to REQUEST_ATTRIBUTE.

The ConfigurationMetadata object

Metadata useful for debugging

Element	Type	Description
currentConfigurationVersions	string[]	A Sorted list of string version numbers of the configuration.
clusterVersion	string	Dynatrace server version.
configurationVersions	integer[]	A Sorted list of the version numbers of the configuration.

    
{
  "tsmMetricKey": "calc:service.mymetric",
  "name": "My Metric",
  "enabled": true,
  "metricDefinition": {
    "metric": "CPU_TIME"
  },
  "managementZones": [
    "zone1"
  ],
  "unit": "MICRO_SECOND",
  "conditions": [
    {
      "attribute": "WEBREQUEST_URL_PATH",
      "comparisonInfo": {
        "type": "STRING",
        "comparison": "BEGINS_WITH",
        "value": "/url_path",
        "negate": false,
        "caseSensitive": false
      }
    }
  ],
  "dimensionDefinition": {
    "name": "my dimension",
    "dimension": "{myPlaceholder}",
    "placeholders": [
      {
        "name": "myPlaceholder",
        "attribute": "WEBREQUEST_URL_PATH",
        "kind": "BEFORE_DELIMITER",
        "delimiterOrRegex": "/booking",
        "normalization": "ORIGINAL",
        "useFromChildCalls": "false"
      }
    ],
    "topX": 10,
    "topXDirection": "DESCENDING",
    "topXAggregation": "AVERAGE"
  }
}

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

Example

In this example, the request inquires about the descriptor of the Top database calls per URL metric, which has the metric key of calc:service.topdbcallsperurl. The metric tracks the number of HTTP calls to databases, where the method is POST. The values of the metric are split by the request name.

The API token is passed in the Authorization header.

Curl

curl -X GET \
  https://mySampleEnv.live.dynatrace.com/api/config/v1/calculatedMetrics/service/calc:service.topdbcallsperurl \
  -H 'Accept: Accept: application/json; charset=utf-8' \
  -H 'Authorization: Api-token abcdefjhij1234567890'

Request URL

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

Response body

{
  "metadata": {
    "configurationVersions": [
      0
    ],
    "clusterVersion": "1.185.0.20191216-221557"
  },
  "tsmMetricKey": "calc:service.topdbcallsperurl",
  "name": "Top database calls per URL",
  "enabled": true,
  "metricDefinition": {
    "metric": "DATABASE_CHILD_CALL_COUNT",
    "requestAttribute": null
  },
  "unit": "COUNT",
  "unitDisplayName": "",
  "entityId": null,
  "managementZones": [
    "Easytravel"
  ],
  "conditions": [
    {
      "attribute": "HTTP_REQUEST_METHOD",
      "comparisonInfo": {
        "type": "HTTP_METHOD",
        "comparison": "EQUALS",
        "value": "POST",
        "negate": false
      }
    }
  ],
  "dimensionDefinition": {
    "name": "{Request:Name}",
    "dimension": "{Request:Name}",
    "placeholders": [],
    "topX": 10,
    "topXDirection": "DESCENDING",
    "topXAggregation": "SINGLE_VALUE"
  }
}

Response code

200