Custom metric ingestion and analysis

Each Dynatrace-supported technology offers multiple "built-in" metrics. Built-in metrics are automatically detected and monitored for you. On average, Dynatrace automatically collects about 500 individual metric timeseries, based on the available technologies and the processes running on your monitored hosts.

If your code exports additional metrics that you want Dynatrace to ingest and analyze, you can register these as "custom" metrics.

Only limited custom metric ingestion and analysis is included in out-of-the-box Dynatrace technology support. Custom metrics consume Davis data units. See Included metrics per host unit for details.

Custom vs built-in metrics

All metrics that are automatically detected and analyzed following installation of OneAgent are considered to be built-in metrics. Built-in metrics cover a wide range of supported technologies, including Apache Tomcat, NGINX, Couchbase, RabbitMQ, Cassandra, Jetty, and many others.

A custom metric is defined as a new type of metric that offers a user-provided metric identifier and unit of measure. The semantics of custom metrics are defined by you and aren't included in the default OneAgent installation. Custom metrics are sent to Dynatrace through various interfaces including the Dynatrace API, OneAgent, ActiveGate, and JMX/PMI extensions. Following the definition of a custom metric, the metric can be reported for multiple monitored components. Each component’s custom metric results in a separate timeseries.

For example, if you define a new custom metric called Files count that counts the newly created files within a directory, this new metric can be collected either for one host or for two individual hosts. Collecting the same metric for two individual hosts results in two timeseries of the same custom metric type, as shown in the example below:

custom metrics

Note: For the purposes of calculating monitoring consumption, collecting the same custom metric for two hosts counts as two separate custom metrics.

Defining and reporting custom metrics

Dynatrace offers the following methods of defining and reporting custom metrics:

To view the custom extensions that are currently enabled within your environment, go to Settings > Monitoring > Monitored technologies and select the Custom extensions tab. See the example below. custom extensions

Data retention for custom metrics

Dynatrace metric-data persistence follows a data-retention strategy that aggregates metrics over time. The data-retention strategy applied to custom metrics is identical to the data-retention strategy applied to built-in timeseries metrics.

Dimensional metrics

Dimensional metrics, also known as "tags" within other timeseries databases, enable fine-grained splitting of the same collected metric. In simple terms, a dimensional metric generates a stacked timeseries chart on a monitored component.

An example of a dimensional metric on a single host is network traffic split by network card. In this example, the metric is collected on a host but the metric itself is split based on all network devices on the host. See example below

dimensional metrics

Each dimensional value (each network card in this example) generates an individual timeseries within the chart. Therefore, for purposes of calculating custom-metric consumption, each dimensional value is counted as a separate custom metric.

JMX/PMI extension custom metrics

You may notice that the number of metrics in the plugin.json file of your JMX/PMI extension differs from the number of billed custom metrics. This is because JMX/PMI extensions provide "splittings" which can be used to define additional dimensions for reported metrics. For each value of a selected property, a separate timeseries metric is created at runtime. The actual number of timeseries metrics depends on the number of distinct values for the selected property.

The following sample shows how to define a metric that provides multiple timeseries with a single metric:

"metrics": [
		"timeseries": {
			"key": "XY.Size",
			"unit": "Count",
			"displayname": "Queue Consumer Count",
			"dimensions": [
		"source": {
			"domain": "com.sample",
			"keyProperties": {
				"type": "XY",
				"name": "*"
			"attribute": "Size",
			"splitting": {
				"name": "name",
				"type": "keyProperty",
				"keyProperty": "name"

In this example, MBeans com.sample:type=XY,name=A and com.sample:type=XY,name=B will result in two timeseries metrics (A and B).

Since such values typically aren't known in advance, and are subject to change, this can lead to an unexpectedly high number of consumed custom metrics. If the values of the property are known in advance, or if only some of the values are of interest, it's recommended that you specify one metric for each value and not use splitting.