Report custom device metric via REST API

The Topology & Smartscape—Custom device API enables you to send a custom metric data point to a custom device in DESK. This request is also able to update the metadata of the custom device.

See Create custom device via the DESK API to learn how to create a custom device without sending data to it.

You can send data to the custom device retrospectively—the custom device endpoint supports the reporting of data up to one hour in the past. However, to ensure the proper functioning of AI root-cause analysis and metric-based alerting, we recommend that data be sent in real time.

For this use case, the series element of the request body is required.

The request consumes and produces an application/json payload.

POST	Managed https://{your-domain}/e/{your-environment-id}/api/v1/entity/infrastructure/custom/{customDeviceId} SaaS https://{your-environment-id}.live.dexp.ae/api/v1/entity/infrastructure/custom/{customDeviceId}

Authentication

To execute this request, you need the Access problem and event feed, metrics, and topology permission assigned to your API token. See the Authentication page to learn how to obtain and use it.

Parameters

Parameter	Type	Description	In	Required
customDeviceId	string	The ID of the custom device. If you use the ID of an existing device, the respective parameters will be updated.	path	required
body	CustomDevicePushMessage	The JSON body of the request. Contains parameters of a custom device.	body	optional

Parameter

Type

Description

Required

customDeviceId

string

The ID of the custom device.

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

path

required

body

CustomDevicePushMessage

The JSON body of the request. Contains parameters of a custom device.

body

optional

Request parameters JSON model

The CustomDevicePushMessage object

Configuration of a custom device.

Element	Type	Description	Required
displayName	string	The name of the custom device that will appear in the user interface.	optional
group	string	User defined group ID of entity. The group ID helps to keep a consistent picture of device-group relations. One of many cases where a proper group is important is service detection: you can define which custom devices should lead to the same service by defining the same group ID for them. If you set a group ID, it will be hashed into the DESK entity ID of the custom device. In that case the custom device can only be part of one custom device group. If you don't set the group ID, DESK will create it based on the ID or type of the custom device. Also, the group will not be hashed into the device ID which means the device may switch groups.	optional
ipAddresses	string[]	The list of IP addresses that belong to the custom device. 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. If you send a value (including an empty value), the existing values will be overwritten. If you send `null` or omit this field, the existing values will be kept.	optional
listenPorts	integer[]	The list of ports the custom devices listens to. These ports are used to 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. If ports are specified, you should also add at least one IP address or a host name for the custom device. If you send a value, the existing values will be overwritten. If you send `null`, or an empty value, or omit this field, the existing values will be kept.	optional
type	string	The technology type definition of the custom device. It must be the same technology type of the metric you're reporting. If you send a value (including an empty value), the existing value will be overwritten. If you send `null` or omit this field, the existing value will be kept.	optional
favicon	string	The icon to be displayed for your custom component within Smartscape. Provide the full URL of the icon file.	optional
configUrl	string	The URL of a configuration web page for the custom device, such as a login page for a firewall or router.	optional
properties	object	The list of key-value pair properties that will be shown beneath the infographics of your custom device.	optional
tags	string[]	List of custom tags that you want to attach to your custom device.	optional
series	EntityTimeseriesData[]	The list of metric values that are reported for the custom device. DESK aggregates all the values you report for a custom device. If you send a value (including an empty value), it will be added to the set of existing values. If you send `null` or omit this field, the set of existing values won't change.	optional
hostNames	string[]	The list of host names related to the custom device. These names 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. If you send a value, the existing values will be overwritten. If you send `null` or an empty value; or omit this field, the existing values will be kept.	optional

The EntityTimeseriesData object

Information about a metric and its data points.

Element Type Description Required

timeseriesId

string

Element	Type	Description	Required
timeseriesId	string	The ID of the metric, where you want to post data points.	required
dimensions	object	Dimensions of the data points you're posting. The key of the metric dimension must be defined earlier in the metric definition.	optional
dataPoints	array[]	List of data points. Each data point is an array, containing the timestamp and the value. Timestamp is UTC milliseconds reported as a number, for example: `1520523365557`. Values can't be reported more than 2 hours into the past! A custom 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.	required

The ID of the metric, where you want to post data points.

required

dimensions

object

Dimensions of the data points you're posting.

The key of the metric dimension must be defined earlier in the metric definition.

optional

dataPoints

array[]

List of data points.

Each data point is an array, containing the timestamp and the value.

Timestamp is UTC milliseconds reported as a number, for example: 1520523365557.

Values can't be reported more than 2 hours into the past!

A custom 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.

required

This is a model of the request body, showing the possible elements. It has to be adjusted for usage in an actual request. See the Example expandable section for working sample request.

      
  {
  "displayName": "coffeeMachine",
  "group": "myCustomDeviceGroup",
  "ipAddresses": [
    "10.0.0.1"
  ],
  "listenPorts": [
    80
  ],
  "favicon": "https://www.freefavicon.com/freefavicons/food/cup-of-coffee-152-78475.png",
  "configUrl": "http://coffee-machine.DESK.internal.com/coffeemachine/manage",
  "type": "coffee machine",
  "properties": {},
  "tags": [
    "office-linz"
  ],
  "series": [
    {
      "timeseriesId": "custom:created.coffee.metric",
      "dimensions": {
        "office": "Linz"
      },
      "dataPoints": [
        [
          1521542929000,
          13
        ]
      ]
    }
  ],
  "hostNames": [
    "coffee-machine.DESK.internal.com"
  ]
}

Response format

Response parameters Response example

Element	Type	Description
entityId	string	The DESK entity ID of the newly created custom device.
groupId	string	The DESK entity ID of the custom device group.

{
	"entityId": "string",
	"groupId": "string"
}

Example

In this example, the request reports two data points of custom:firewall.connections.dropped for the idOfmyCustomDevice device. The data points (with value 460 for the 1539860400000 time stamp and value 456 for the 1539860460000 time stamp) belong to the ethernetcard1 value of the nic dimension.

The request also reports two more data points of the same metric, but for ethernetcard2 in the same dimension, and it updates device metadata by adding a property and a tag.

The API token is passed in the Authorization header.

The request returns the IDs of the custom device (see entityId) and its group (see groupId) as confirmation.

You can download or copy the example request body to try it out on your own.

Curl

curl -X POST \
  https://mySampleEnv.live.dexp.ae/api/v1/entity/infrastructure/custom/idOfmyCustomDevice \
  -H 'Authorization: Api-Token abcdefjhij1234567890' \
  -H 'Content-Type: application/json' \  
  -d '{  
  "tags": [
    "tag2"
  ],
  "type": "F5-Firewall",
  "properties" : {    
    "Sample Property 2": "Sample value 2"
  },
  "series" : [
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard1"  
      },
      "dataPoints" : [
        [ 1539860400000, 460 ],
        [ 1539860460000, 456 ]
       ]
    },
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard2"  
      },
      "dataPoints" : [
        [ 1539860430000, 439 ],
        [ 1539860490000, 460 ]
       ]
    }
  ]
}'

Request URL

https://mySampleEnv.live.dexp.ae/api/v1/entity/infrastructure/custom/idOfmyCustomDevice

Request body


        api-examples/custom-device/report-metric.json

Download

{
  "tags": [
    "tag2"
  ],
  "type": "F5-Firewall",
  "properties" : {
    "Sample Property 2": "Sample value 2"
  },
  "series" : [
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard1"
      },
      "dataPoints" : [
        [ 1539860400000, 460 ],
        [ 1539860460000, 456 ]
       ]
    },
    {
      "timeseriesId" : "custom:firewall.connections.dropped",
      "dimensions" : {
        "nic" : "ethernetcard2"
      },
      "dataPoints" : [
        [ 1539860430000, 439 ],
        [ 1539860490000, 460 ]
       ]
    }
  ]
}

Response body

{
  "entityId": "CUSTOM_DEVICE-6A567B33AADC306E",
  "groupId": "CUSTOM_DEVICE_GROUP-FC2E2ABF54F513D8"
}

Response code

200

Result

Metrics of the custom device in chart