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

• Metrics

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

MQTT

Endpoint

mqtt: /metric/get

Authorized User Role

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

POST /metric/getMetricList

Authorized User Role

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.

GetDeviceSchema

Endpoint

POST /metric/getDeviceSchema

Authorized User Role

user

Request Body

Field	Type
cloudId	string

Response

A object.

Fetch

Fetch metric values.

This API fetches multiple metric values in a single request.

Endpoint

POST /metric/fetch

Authorized User Role

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 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

MQTT

Endpoint

mqtt: /metric/set

Authorized User Role

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.