Timeseries API - Custom metrics

The Timeseries API enables you to create new kinds of network components and to register and send custom metrics for these devices.

A custom network device is any part of your environment that can't run Dynatrace OneAgent. Examples include Firewalls, DataPower gateways, cloud databases, and any other network appliance such as a proxy or gateway. By using the Dynatrace API, it's possible for your own networked box to send custom metrics into Dynatrace based on the native properties of these devices, or to write your own scripts that pull the metrics from your networked or cloud-networked box.

As Dynatrace AI and intelligent problem detection and correlation depend on topological information, each custom device should announce its position within your network infrastructure. By providing the correct IP address, along with a detailed description of the custom device properties, you enable Dynatrace to automatically map your custom device into your existing Smartscape environment.

By default, there's a free quota of 100 custom metrics per month that you can report using the Dynatrace API. Each metric dimension counts as a separate metric. To increase or eliminate this quota, contact your Dynatrace account representative. Custom metric ingestion and analysis isn't included in out-of-the-box Dynatrace technology support or basic Dynatrace licensing. Custom metrics involve additional cost and separate licensing. For details, see How to calculate monitoring consumption.

The following is a typical sequence of API calls for custom metrics usage:

  1. Create a custom metric with a PUT custom metric call to this endpoint.
  2. Create a custom device with a POST custom device call to the Custom device endpoint. This step is optional; you can send the data straight away—the device will be created automatically.
  3. Send data to the custom device with a POST metric to the custom device call to the Custom device endpoint.
  4. If you no longer need the custom device, you can delete it with a DELETE custom metric call to this endpoint. Be careful with this one: it will also delete all the data you sent to the custom device earlier.

PUT custom metric

Registers your custom metric. You need to specify the ID, the display name, and type of the metric.

If you use the ID of an existing metric, the respective parameters will be updated.

The request consumes and produces an application/json payload.

  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/timeseries/{timeseriesIdentifier}

DELETE custom metric

Deletes the specified custom metric. If you delete a metric definition, you lose all of that metric's data, so be careful with deletes.

Built-in metrics can't be deleted.

  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/timeseries/{timeseriesIdentifier}
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/timeseries/{timeseriesIdentifier}

Usage of custom metric

After you've registered all your custom metrics, it's time to create a custom device and send some metric values to it. As with all OneAgent-based information, you don't need to register a custom device. Just start sending information and the device will be created automatically.

To send metric information for a custom device, use the custom device endpoint. See Topology & Smartscape API - Custom device to learn how.