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 of such network devices include Firewalls, DataPower gateways, cloud databases, and any other network appliance such as a proxy or gateway. By using this 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 send the metrics in place of the network or cloud network 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 network 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.

The first step in sending any custom metrics into Dynatrace is to correctly register the type and ID of the custom metric. By sending a HTTP PUT request to the existing timeseries REST endpoint, an API consumer is able to register a new kind of metric within the given environment. Refer to the following section for registering and working with custom metrics.

List all custom metrics

The Dynatrace API timeseries endpoint covers all metric-relevant information. A HTTP GET request lists all available metric definitions within your given environment. You can easily check which metrics are defined and exported by your Dynatrace environment by calling:

HTTP GET https://{id}.live.dynatrace.com/api/v1/timeseries

The call will list all the defined and exposed metrics, no matter if the metric is built-in, a plugin, or a custom API-defined metric. Here is example output:

[
  {
    timeseriesId: "custom:firewall.connections.dropped",
    displayName: "Dropped TCP connections",
    dimensions: [
      "CUSTOM_DEVICE"
    ],
    aggregationTypes: [
      "AVG",
      "SUM",
      "MIN",
      "MAX"
    ],
    unit: "%",
    filter: "CUSTOM",
    types: [
      "F5-Firewall"
    ]
  }
]

Use the filter parameter (BUILTIN, PLUGIN, or CUSTOM) to list only the custom-defined metrics, as shown below:

HTTP GET https://{id}.live.dynatrace.com/api/v1/timeseries?filter=CUSTOM

Register your custom metric

The same timeseries endpoint is used to register new custom metrics by sending a HTTP PUT call, where the payload contains the metadata for your new metric, as shown in the example below. The metadata payload contains the display name of your metric, the unit definition (‘Count’, ‘Percent’, ), an optional dimension key, and a technology type definition, which is used to group your metrics under a logical technology name. Metrics must be assigned a software technology type that is identical to the technology type of the custom device you are sending the metric to. If you define your custom device using type F5 firewall you must also register all custom metrics as type F5 firewall. The HTTP PUT request refers to the unique metric identifier (custom:firewall.connections.dropped) that will be used later to send in the metric values.

HTTP PUT https://{id}.live.dynatrace.com/api/v1/timeseries/custom:firewall.connections.dropped/

with following payload:

{
	"displayName" : "Dropped TCP connections",
	"unit" : "Count",
	"dimensions": [
		"nic"
	],
	"types": [
		"F5-Firewall"
	]
}

The HTTP 200 return code signals that the registration of your custom metric has been accepted. You can cross-check the registration by listing the registered metrics that should now contain your newly created metric.

The following list details the meta-information necessary to register a new metric:

  • displayName: The display name of the metric that will be shown in the UI. The display name for your metrics is limited to 256 characters.
  • unit: The definition of the unit that will be used for this metric. See below for a detailed definition of possible metric units.
  • dimensions: Definition of a metric dimension key that will be used to report multiple dimensions. An example here could be defining a dimension key with name nic, as shown in the example above, in order to report the metric for different network cards for the same firewall. The name of dimensions is only allowed to contain alphanumeric characters and '.', '-' or '_'.
  • types: List of technology types for which this metric is registered. These types are used by the UI to show metrics in technology-related groups.

Metric units

  • Time: 'NanoSecond','MicroSecond','MilliSecond','Second';
  • Information: 'Bit','Byte','KiloByte','KibiByte','MegaByte','MebiByte','GigaByte','GibiByte';
  • Information per time: 'BytePerSecond', 'BytePerMinute','BitPerSecond','BitPerMinute','KiloBytePerSecond', 'KiloBytePerMinute','KibiBytePerSecond','KibiBytePerMinute','MegaBytePerSecond','MegaBytePerMinute','MebiBytePerSecond', 'MebiBytePerMinute';
  • Ratio: 'Ratio','Percent','Promille';
  • Count: 'Count','PerSecond','PerMinute';

Delete a custom metric

You can delete your custom metric using a HTTP DELETE request on a custom metric id. If you delete a metric definition, you will lose any metrics that you sent in earlier; so be very careful with deletes.

HTTP DELETE https://{id}.live.dynatrace.com/api/v1/timeseries/ **custom:firewall.connections.dropped**

Start reporting metrics for a custom device

After you've registered all your custom metrics, it's time to send some metric values to a new custom device. 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 topology endpoint and push custom device meta information as well as all metric information through a HTTP POST request.

Again, the custom unique ID within the URL (F5firewall24) defines the custom device identifier. HTTP POST https://.live.dynatrace.com/api/v1/entity/infrastructure/custom/ F5firewall24

With payload:

{
  "displayName" : "F5 Firewall 24",
  "ipAddresses" : ["172.16.115.211"],
  "listenPorts" : ["9999"],
  "type" : "F5-Firewall",
  "favicon" : "http://assets.dynatrace.com/global/icons/f5.png",
  "configUrl" : "http://172.16.115.211:8080",
  "tags": ["user defined tag", "tag2"],
  "properties" : { "prop1" : "propvalue" },
  "series" : [
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : { "nic" : "ethernetcard1"  },
      "dataPoints" : [ [ <timestamp as a number, for example: 1495520570871>  , <value> ] ]
    },
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : { "nic" : "ethernetcard2"  },
      "dataPoints" : [ [ <timestamp as a number, for example: 1495520570871>  , <value> ] ]
    }
  ]
}

The HTTP 200 response indicates that the custom device meta information was accepted and you can start to work with your custom device within Dynatrace.

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.

The following list details the meta-information necessary to send meta-information and metric values for a custom component:

  • displayName: The display name of the component that will be used within the UI.
  • ipAddresses: List of IP addresses that belong to the component. These addresses are used to automatically discover the horizontal communication relationship between this component and all other observed components within Smartscape. Once a connection is discovered, it is automatically mapped and shown within Smartscape.
  • listenPorts: More detailed information about how this component accepts communication from other components on the network-port level. This information is used to automatically connect process-to-process communication relationships with the custom component.
  • type: A defined software technology type for this custom component. Please make sure that you only report metrics where the technology type matches the component's technology type.
  • favIcon: A URL where we can fetch a grayscale or monochrome icon that will be used for your custom component. The icon will automatically invert the color when displayed in Smartscape.
  • configURL: A URL used to directly link to the configuration web page of the entity, such as a login page for a firewall or router.
  • tags: List of custom user labels that you want attached to your custom component.
  • properties: A list of key value pair properties that will be shown beneath the infographics of your custom component.
  • series: List of metric values that are reported for the custom component. A series object always contains the metric identifier, a timestamp in UTC milliseconds (reported as a number, for example: 1495520570871), and the metrics dimension information. The key of the metric dimension (for example, nic) must be defined earlier in the metric definition. The metrics are then sent for nic : ethernetcard1 and nic : ethernetcard2. One important constraint here is the fact that values can't be reported further than 2 hours into the past! A metric must be registered before you can report a metric value. Therefore, the timestamp for reporting a value must be after the registration time of the metric.

Please keep in mind that components meta-information must be sent upon creation or during updates only. All the other metric value reports don't have to contain component meta-information.

Once your custom devices begin to send in metric values, you will find the metrics on the custom charting tile, as shown below.