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

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

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

Response

Paged response.

Field	Type	Notes
data	array	An array of devices owned by the user.
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

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

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.

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

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

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.

GetDeviceSchema

Get a device schema.

Endpoint

POST /metric/getDeviceSchema

Authorized User Role

user

Request Body

Field	Type	Notes
cloudId	string	Cloud ID.

Response

Schema definition.

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			Metric name. If not provided, returns a list of available metrics.
model	string			Database model.

Response

Object Record.

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.

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.