Skip to content

Metric

API to manage metrics including the ability to get and set metrics, and to get a list of available metrics.

The Ioto service creates metrics for device and service data. It stores the current live and historical metric values. Metrics are calculated for for the last "5 minutes", hour, day, week, month, and year. Statistics are kept for the average, min, max, count and the sum of metric values.

Metrics are named and grouped into Namespaces with metric Dimensions selecting instances of a metric for a specific resoure.

See Also


Get

Get an accumulated metric.

This API is used by devices to retrieve a metric statistic over the MQTT protocol.

To get metrics over REST HTTP, use the fetch API.

Protocol

1
MQTT

Endpoint

1
mqtt: /metric/get

Authorized User Role

1
device

Request Body

Field Type Default Notes
dimensions object Dimensions for metric.
metric string Metric name.
period number 300 Metric timespan period.
statistic string avg Metric statistic.

Response

Paged response.

Field Type Notes
data array An array of merics.
next string Paged cursor to use for the next page of items.
prev string Pages cursor to use for the previous page of items.

Metric

An array of Metric items.

Field Type Notes
dimensions object Dimensions for the metric.
metric string Metric name.
namespace string Always set to Embedthis/Device.
owner string The service owning the metric.
period number Metric timespan period.
points array Array of data points.
samples number Number of data points in the period.

Dimensions

Dimensions for the metric.

Field Type
* any

Point

An array of Points items.

Field Type Notes
value number Metric value.
timestamp number Last update to the metric value in seconds since Jan 1, 1970.
count number Number of data values contributing to the metric value.

GetMetricList

Get a list of available metrics.

Endpoint

1
POST /metric/getMetricList

Authorized User Role

1
user

Request Body

Field Type Required Role Notes
cloudId string yes owner Override, device cloud containing the metrics.
namespace string Metric namespace. If not provided, the API returns a list of namespaces.
metric string If not provided, returns a list of available metrics.

Response

Field Type Notes
namespaces array Returns the requested namespace. If not provided, returns a list of available namespaces.
metrics array If a namespace is provided, returns a list of available metrics.
dimensions array If a namespace and metric are provided, returns a list of available metric dimensions.

Fetch

Fetch metric values.

This API fetches multiple metric values in a single request.

Endpoint

1
POST /metric/fetch

Authorized User Role

1
user

Request Body

Field Type Required Notes
items array yes Array of metric requests.
deviceId string yes Device ID owning the metrics.

Metric Request

An array of Items items.

Field Type Notes
accumulate boolean Accumulate result into a single result.
cloudId string Device Cloud ID.
dimensions object Dimensions for metric.
field string Database model field name.
metric string Metric name.
model string Database model name.
namespace string Must be set to Embedthis/Device.
period number Metric timespan period.
statistic string Metric statistic. Select from: avg, min, max, count, sum.

Response

Paged response.

Field Type Notes
data array An array of merics.
next string Paged cursor to use for the next page of items.
prev string Pages cursor to use for the previous page of items.

Metric

An array of Metric Array items.

Field Type Notes
dimensions object Dimensions for the metric.
metric string Metric name.
namespace string Always set to Embedthis/Device.
owner string The service owning the metric.
period number Metric timespan period.
points array Array of data points (see below).
samples number Number of data points in the period.
* any

Dimensions

Dimensions for the metric.

Field Type
* any

Point

An array of Points items.

Field Type Notes
value number Metric value.
timestamp number Last update to the metric value in seconds since Jan 1, 1970.
count number Number of data values contributing to the metric value.

Set

Set a metric value.

This API is used by devices to emit a metric value. It is sent over MQTT rather than via REST.

Protocol

1
MQTT

Endpoint

1
mqtt: /metric/set

Authorized User Role

1
device

Request Body

Field Type Notes
metric string Metric name.
value number Metric value.
dimensions array Array of dimensions for metric.
buffer object Metric buffering options.