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 | |
Endpoint
1 | |
Authorized User Role
1 | |
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 | |
Authorized User Role
1 | |
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 | |
Authorized User Role
1 | |
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 | array | 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 |
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 | |
Endpoint
1 | |
Authorized User Role
1 | |
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. |