Service metrics API - POST a metric
Creates a new calculated service metric.
The request consumes and produces an application/json payload.
| POST | SaaS | https://{your-environment-id}.live.dynatrace.com/api/config/v1/calculatedMetrics/service |
| Environment ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/calculatedMetrics/service |
Authentication
To execute this request, you need an access token with WriteConfig scope.
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.
The JSON body of the request. Contains parameters of the new calculated service metric.
Request body objects
The CalculatedServiceMetric object
Descriptor of a calculated service metric.
The set of conditions for the metric usage.
All the specified conditions must be fulfilled to use the metric.
Parameters of a definition of a calculated service metric.
The metric is enabled (true) or disabled (false).
Restricts the metric usage to the specified service.
This field is mutually exclusive with the managementZones field.
Metric should (true) or not (false) ignore muted requests.
Restricts the metric usage to specified management zones.
This field is mutually exclusive with the entityId field.
The displayed name of the metric.
The key of the calculated service metric.
The unit of the metric.
AMPEREBILLIONBITBIT_PER_HOURBIT_PER_MINUTEBIT_PER_SECONDBYTEBYTE_PER_HOURBYTE_PER_MINUTEBYTE_PER_SECONDCORESCOUNTDAYDECIBEL_MILLI_WATTGIBI_BYTEGIBI_BYTE_PER_HOURGIBI_BYTE_PER_MINUTEGIBI_BYTE_PER_SECONDGIGAGIGA_BYTEGIGA_BYTE_PER_HOURGIGA_BYTE_PER_MINUTEGIGA_BYTE_PER_SECONDHERTZHOURKIBI_BYTEKIBI_BYTE_PER_HOURKIBI_BYTE_PER_MINUTEKIBI_BYTE_PER_SECONDKILOKILO_BYTEKILO_BYTE_PER_HOURKILO_BYTE_PER_MINUTEKILO_BYTE_PER_SECONDKILO_METRE_PER_HOURMEBI_BYTEMEBI_BYTE_PER_HOURMEBI_BYTE_PER_MINUTEMEBI_BYTE_PER_SECONDMEGAMEGA_BYTEMEGA_BYTE_PER_HOURMEGA_BYTE_PER_MINUTEMEGA_BYTE_PER_SECONDMETRE_PER_HOURMETRE_PER_SECONDMICRO_SECONDMILLIONMILLI_CORESMILLI_SECONDMILLI_SECOND_PER_MINUTEMINUTEMONTHMSUNANO_SECONDNANO_SECOND_PER_MINUTENOT_APPLICABLEPERCENTPER_HOURPER_MINUTEPER_SECONDPIXELPROMILLERATIOSECONDSTATETRILLIONUNSPECIFIEDVOLTWATTWEEKYEAR
The display name of the metric's unit.
Only applicable when the unit parameter is set to UNSPECIFIED.
The Condition object
A condition of a rule usage.
The attribute to be matched.
Note that for a service property attribute you must use the comparison of the FAST_STRING type.
ACTOR_SYSTEMAKKA_ACTOR_CLASS_NAMEAKKA_ACTOR_MESSAGE_TYPEAKKA_ACTOR_PATHAPPLICATION_BUILD_VERSIONAPPLICATION_ENVIRONMENTAPPLICATION_NAMEAPPLICATION_RELEASE_VERSIONAZURE_FUNCTIONS_FUNCTION_NAMEAZURE_FUNCTIONS_SITE_NAMECICS_PROGRAM_NAMECICS_SYSTEM_IDCICS_TASK_IDCICS_TRANSACTION_IDCICS_USER_IDCPU_TIMECTG_GATEWAY_URLCTG_PROGRAMCTG_SERVER_NAMECTG_TRANSACTION_IDCUSTOMSERVICE_CLASSCUSTOMSERVICE_METHODDATABASE_CHILD_CALL_COUNTDATABASE_CHILD_CALL_TIMEDATABASE_HOSTDATABASE_NAMEDATABASE_STATEMENTDATABASE_TYPEDATABASE_URLDISK_IO_TIMEERROR_COUNTESB_APPLICATION_NAMEESB_INPUT_TYPEESB_LIBRARY_NAMEESB_MESSAGE_FLOW_NAMEEXCEPTION_CLASSEXCEPTION_MESSAGEFAILED_STATEFAILURE_REASONFLAW_STATEHTTP_REQUEST_METHODHTTP_STATUSHTTP_STATUS_CLASSIMS_PROGRAM_NAMEIMS_TRANSACTION_IDIMS_USER_IDIO_TIMEIS_KEY_REQUESTLAMBDA_COLDSTARTLOCK_TIMEMESSAGING_DESTINATION_TYPEMESSAGING_IS_TEMPORARY_QUEUEMESSAGING_QUEUE_NAMEMESSAGING_QUEUE_VENDORNETWORK_IO_TIMENON_DATABASE_CHILD_CALL_COUNTNON_DATABASE_CHILD_CALL_TIMEPROCESS_GROUP_NAMEPROCESS_GROUP_TAGREMOTE_ENDPOINTREMOTE_METHODREMOTE_SERVICE_NAMEREQUEST_NAMEREQUEST_TYPERESPONSE_TIMERESPONSE_TIME_CLIENTRMI_CLASSRMI_METHODSERVICE_DISPLAY_NAMESERVICE_NAMESERVICE_PORTSERVICE_PUBLIC_DOMAIN_NAMESERVICE_REQUEST_ATTRIBUTESERVICE_TAGSERVICE_TYPESERVICE_WEB_APPLICATION_IDSERVICE_WEB_CONTEXT_ROOTSERVICE_WEB_SERVER_NAMESERVICE_WEB_SERVICE_NAMESERVICE_WEB_SERVICE_NAMESPACESUSPENSION_TIMETOTAL_PROCESSING_TIMEWAIT_TIMEWEBREQUEST_QUERYWEBREQUEST_RELATIVE_URLWEBREQUEST_URLWEBREQUEST_URL_HOSTWEBREQUEST_URL_PATHWEBREQUEST_URL_PORTWEBSERVICE_ENDPOINTWEBSERVICE_METHODZOS_CALL_TYPE
Type-specific comparison for attributes. The actual set of fields depends on the type of the comparison. Find the list of actual objects in the description of the type field or see Service metrics API - JSON models.
The ComparisonInfo object
Type-specific comparison for attributes. The actual set of fields depends on the type of the comparison. Find the list of actual objects in the description of the type field or see Service metrics API - JSON models.
Operator of the comparision. You can reverse it by setting negate to true.
Reverse the comparison operator. For example, it turns equals into does not equal.
Defines the actual set of fields depending on the value. See one of the following objects:
STRING-> StringComparisonInfoNUMBER-> NumberComparisonInfoBOOLEAN-> BooleanComparisonInfoHTTP_METHOD-> HttpMethodComparisonInfoSTRING_REQUEST_ATTRIBUTE-> StringRequestAttributeComparisonInfoNUMBER_REQUEST_ATTRIBUTE-> NumberRequestAttributeComparisonInfoZOS_CALL_TYPE-> ZosComparisonInfoIIB_INPUT_NODE_TYPE-> IIBInputNodeTypeComparisonInfoESB_INPUT_NODE_TYPE-> ESBInputNodeTypeComparisonInfoFAILED_STATE-> FailedStateComparisonInfoFLAW_STATE-> FlawStateComparisonInfoFAILURE_REASON-> FailureReasonComparisonInfoHTTP_STATUS_CLASS-> HttpStatusClassComparisonInfoTAG-> TagComparisonInfoFAST_STRING-> FastStringComparisonInfoSERVICE_TYPE-> ServiceTypeComparisonInfo
BOOLEANESB_INPUT_NODE_TYPEFAILED_STATEFAILURE_REASONFAST_STRINGFLAW_STATEHTTP_METHODHTTP_STATUS_CLASSIIB_INPUT_NODE_TYPENUMBERNUMBER_REQUEST_ATTRIBUTESERVICE_TYPESTRINGSTRING_REQUEST_ATTRIBUTETAGZOS_CALL_TYPE
The value to compare to.
The values to compare to.
The AnyValue object
A schema representing an arbitrary value type.
The DimensionDefinition object
Parameters of a definition of a calculated service metric.
The dimension value pattern.
You can define custom placeholders in the placeholders field and use them here.
The name of the dimension.
The list of custom placeholders to be used in a dimension value pattern.
The number of top values to be calculated.
The aggregation of the dimension.
AVERAGECOUNTMAXMINOF_INTEREST_RATIOOTHER_RATIOSINGLE_VALUESUM
How to calculate the topX values.
ASCENDINGDESCENDING
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.
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.
COUNTFIRSTLAST
The attribute to extract from. You can only use attributes of the string type.
ACTOR_SYSTEMAKKA_ACTOR_CLASS_NAMEAKKA_ACTOR_MESSAGE_TYPEAKKA_ACTOR_PATHAPPLICATION_BUILD_VERSIONAPPLICATION_ENVIRONMENTAPPLICATION_NAMEAPPLICATION_RELEASE_VERSIONAZURE_FUNCTIONS_FUNCTION_NAMEAZURE_FUNCTIONS_SITE_NAMECICS_PROGRAM_NAMECICS_SYSTEM_IDCICS_TASK_IDCICS_TRANSACTION_IDCICS_USER_IDCPU_TIMECTG_GATEWAY_URLCTG_PROGRAMCTG_SERVER_NAMECTG_TRANSACTION_IDCUSTOMSERVICE_CLASSCUSTOMSERVICE_METHODDATABASE_CHILD_CALL_COUNTDATABASE_CHILD_CALL_TIMEDATABASE_HOSTDATABASE_NAMEDATABASE_STATEMENTDATABASE_TYPEDATABASE_URLDISK_IO_TIMEERROR_COUNTESB_APPLICATION_NAMEESB_INPUT_TYPEESB_LIBRARY_NAMEESB_MESSAGE_FLOW_NAMEEXCEPTION_CLASSEXCEPTION_MESSAGEFAILED_STATEFAILURE_REASONFLAW_STATEHTTP_REQUEST_METHODHTTP_STATUSHTTP_STATUS_CLASSIMS_PROGRAM_NAMEIMS_TRANSACTION_IDIMS_USER_IDIO_TIMEIS_KEY_REQUESTLAMBDA_COLDSTARTLOCK_TIMEMESSAGING_DESTINATION_TYPEMESSAGING_IS_TEMPORARY_QUEUEMESSAGING_QUEUE_NAMEMESSAGING_QUEUE_VENDORNETWORK_IO_TIMENON_DATABASE_CHILD_CALL_COUNTNON_DATABASE_CHILD_CALL_TIMEPROCESS_GROUP_NAMEPROCESS_GROUP_TAGREMOTE_ENDPOINTREMOTE_METHODREMOTE_SERVICE_NAMEREQUEST_NAMEREQUEST_TYPERESPONSE_TIMERESPONSE_TIME_CLIENTRMI_CLASSRMI_METHODSERVICE_DISPLAY_NAMESERVICE_NAMESERVICE_PORTSERVICE_PUBLIC_DOMAIN_NAMESERVICE_REQUEST_ATTRIBUTESERVICE_TAGSERVICE_TYPESERVICE_WEB_APPLICATION_IDSERVICE_WEB_CONTEXT_ROOTSERVICE_WEB_SERVER_NAMESERVICE_WEB_SERVICE_NAMESERVICE_WEB_SERVICE_NAMESPACESUSPENSION_TIMETOTAL_PROCESSING_TIMEWAIT_TIMEWEBREQUEST_QUERYWEBREQUEST_RELATIVE_URLWEBREQUEST_URLWEBREQUEST_URL_HOSTWEBREQUEST_URL_PATHWEBREQUEST_URL_PORTWEBSERVICE_ENDPOINTWEBSERVICE_METHODZOS_CALL_TYPE
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.
The closing delimiter string to look for.
Required if the kind value is BETWEEN_DELIMITER. Not applicable otherwise.
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
AFTER_DELIMITERBEFORE_DELIMITERBETWEEN_DELIMITERORIGINAL_TEXTREGEX_EXTRACTION
The name of the placeholder. Use it in the naming pattern as {name}.
The format of the extracted string.
ORIGINALTO_LOWER_CASETO_UPPER_CASE
The request attribute to extract from.
Required if the kind value is SERVICE_REQUEST_ATTRIBUTE. Not applicable otherwise.
Defines valid sources of request attributes for conditions or placeholders.
If true request attribute will be taken from a child service call.
Only applicable for the SERVICE_REQUEST_ATTRIBUTE attribute. Defaults to false.
The PropagationSource object
Defines valid sources of request attributes for conditions or placeholders.
Use only request attributes from services that belong to this management zone.. Use either this or serviceTag
Use only request attributes from services that have this tag. Use either this or managementZone
The UniversalTag object
Use only request attributes from services that have this tag. Use either this or managementZone
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.
AWSAWS_GENERICAZURECLOUD_FOUNDRYCONTEXTLESSENVIRONMENTGOOGLE_COMPUTE_ENGINEKUBERNETES
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.
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.
The UniversalTagKey object
AWSAWS_GENERICAZURECLOUD_FOUNDRYCONTEXTLESSENVIRONMENTGOOGLE_COMPUTE_ENGINEKUBERNETES
The ConfigurationMetadata object
Metadata useful for debugging
Dynatrace version.
A sorted list of the version numbers of the configuration.
A sorted list of version numbers of the configuration.
The CalculatedMetricDefinition object
The definition of a calculated service metric.
The metric to be captured.
CAPTURED_FULL_SERVICE_CALLSCPU_TIMEDATABASE_CHILD_CALL_COUNTDATABASE_CHILD_CALL_TIMEDISK_IO_TIMEEXCEPTION_COUNTFAILED_REQUEST_COUNTFAILED_REQUEST_COUNT_CLIENTFAILURE_RATEFAILURE_RATE_CLIENTHTTP_4XX_ERROR_COUNTHTTP_4XX_ERROR_COUNT_CLIENTHTTP_5XX_ERROR_COUNTHTTP_5XX_ERROR_COUNT_CLIENTIO_TIMELOCK_TIMENETWORK_IO_TIMENON_DATABASE_CHILD_CALL_COUNTNON_DATABASE_CHILD_CALL_TIMEPROCESSING_TIMEREQUEST_ATTRIBUTEREQUEST_COUNTRESPONSE_TIMERESPONSE_TIME_CLIENTSUCCESSFUL_REQUEST_COUNTSUCCESSFUL_REQUEST_COUNT_CLIENTWAIT_TIME
The request attribute to be captured.
Only applicable when the metric parameter is set to REQUEST_ATTRIBUTE.
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.
{"conditions": [{"attribute": "WEBREQUEST_URL_PATH","comparisonInfo": {"caseSensitive": false,"comparison": "BEGINS_WITH","negate": false,"type": "STRING","value": "/url_path"}}],"dimensionDefinition": {"dimension": "{myPlaceholder}","name": "my dimension","placeholders": [{"attribute": "WEBREQUEST_URL_PATH","delimiterOrRegex": "/booking","kind": "BEFORE_DELIMITER","name": "myPlaceholder","normalization": "ORIGINAL","useFromChildCalls": "false"}],"topX": 10,"topXAggregation": "AVERAGE","topXDirection": "DESCENDING"},"enabled": true,"managementZones": ["zone1"],"metricDefinition": {"metric": "CPU_TIME"},"name": "My Metric","tsmMetricKey": "calc:service.mymetric","unit": "MICRO_SECOND"}
Response
Response codes
Success. The calculated service metric has been created. Response contains the key of the new metric.
Response body objects
The EntityShortRepresentation object
The short representation of a Dynatrace entity.
A short description of the Dynatrace entity.
The ID of the Dynatrace entity.
The name of the Dynatrace entity.
Response body JSON model
{"description": "Dynatrace entity for the REST API example","id": "6a98d7bc-abb9-44f8-ae6a-73e68e71812a","name": "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.
| POST | SaaS | https://{your-environment-id}.live.dynatrace.com/api/config/v1/calculatedMetrics/service/validator |
| Environment ActiveGate | https://{your-activegate-domain}:9999/e/{your-environment-id}/api/config/v1/calculatedMetrics/service/validator |
Authentication
To execute this request, you need an access token with WriteConfig scope.
To learn how to obtain and use it, see Tokens and authentication.
Response
Response codes
Validated. The submitted configuration is valid. Response doesn't have a body.
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 dt0c01.abc123.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
{"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