What does the Custom network devices and metrics API provide?

The custom network devices and metrics API allows all Dynatrace users 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 through the REST API, along with a detailed description of the custom device properties, Dynatrace is automatically able to map your custom device into your existing Smartscape environment.

Dynatrace provides you with a free quota of 100 metrics per month for each Dynatrace SaaS environment or Dynatrace Managed cluster.

PUT custom metric

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

The request consumes and produces application/json payload.

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

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

GET custom metrics

Lists all custom metric available in your Dynatrace environment.

The request produces application/json payload.

GET
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/timeseries?filter=CUSTOM
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/timeseries?filter=CUSTOM

DELETE custom metric

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

Built-in metrics can't be deleted.

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

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 infrastructure endpoint.

POST custom device

Creates custom device with a specified name in your Dynatrace environment.

The request consumes and produces application/json payload.

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

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/<device_ID>
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/entity/infrastructure/custom/<device_ID>

POST custom metric values

Sends custom metric data point to the custom device in Dynatrace.

The request uses the same endpoint and the previously described POST custom device request. Therefore it is able to update the metadata of the custom device.

The request consumes and produces application/json payload.

POST
  • Managed https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/<device_ID>
  • SaaS https://{your-environment-id}.live.dynatrace.com/api/v1/entity/infrastructure/custom/<device_ID>

Dynatrace will show the custom device on the host and process level within Smartscape, as the device itself can contain a network IP address as well as listening ports. Once communication is detected between a OneAgent-instrumented host and the custom device, the connection will be automatically shown within Smartscape. Once your custom devices begin to send in metric values, you can use the metrics on the custom charting tile.