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. See Free tier of custom metrics for details. To arrange for additional custom metric ingestion and analysis, you'll need to set up a Data ingestion and analytics license. Contact Dynatrace Sales 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 plugins. 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 plugins that are currently enabled within your environment, go to Settings > Monitoring > Monitored technologies and select the Custom plugins tab. See the example below. custom plugins

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 plugin custom metrics

You may notice that the number of metrics in the plugin.json file of your JMX/PMI plugin differs from the number of billed custom metrics. This is because JMX/PMI plugins 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.