Metrics

Device Metrics refer to data points and measurements that provide insights into the performance, availability, and efficiency of your devices and device cloud. Metrics are essential for monitoring and managing your devices and ensuring the overall health of your device pool.

The Ioto service provides a set of standard metrics and you can create custom metrics based on your device specific data.

Using device data that is synchronized to the cloud from your devices, you can automatically create custom metrics from the data stream.

Metric Timespans

When the Ioto service creates metrics, it keeps the current live value and stores the historical metric values so you can monitor historical trends. Ioto metrics maintains statistics for the last "5 minutes", "hour", "day", "week" "month", or "year". Each of these ranges contain 10-12 data points.

When querying metrics, you can provide any data range and the relevant underlying metric data will be returned. You can also specify a date range start time and duration for metrics from any point in time.

These metrics can then be monitored and displayed by device apps as a single metric value or as set of values over time as a graph.

Metric Statistics

For each timespan, you can query the average, minimum, maximum or sum value for the metric.

Metric Naming

Metrics are scoped via a set of naming properties including:

• namespace
• metric name
• dimensions

The namespace is a global name to group related metrics. Currently, this must be set to Embedthis/Device.

The metric name is the specific metric name. For example: a device's temperature.

The dimensions select specific instances of a metric. For example, each device may have a temperature metric and we may also have an overall device pool average temperature metric. Ioto treats each unique combination of dimensions as a separate metric. Enter the dimensions as a comma separated list of dimensions. For example:

dimensions = "Process,Module"

Defining Metrics

Metrics can be created three ways:

• Via Builder automation actions that create metrics based upon trigger condidtions and values.
• Via the Database schema definition
• Via the Ioto Agent ioMetric API

See Automations for more information on how to create Builder automations.

Database Schema Metrics

Metrics can be created via the device database schema definition. In the process section for a schema model, define a metrics array of metric definitions. Each definition selects a data item value to be converted to a metric.

For example:

const DeviceSchema = {
    process: {
        Fault:   { 
            sync: 'up' 
            metrics: [{
                namespace: 'Embedthis/Device',
                fields: [{Temperature: 'temp'}],
                dimensions: [{Device: 'deviceId'}]
            }]
        }
    },
    ...
}

This will automatically create a Temperature metric in the Embedthis/Device namespace based upon the database item's temp attribute whenever the temperature value changes.

Metric definitions may contain the following properties:

Property	Type	Description
buffer	map	Metric buffering directives. Defaults to null
dimensions	array	Array of metric dimensions. Defaults to null
fields	array	Array of metrics to create. Array metric entries may contain field attribute names or a map of a field attribute to a metric name.
namespace	string	Metric namespace for the metric. Must be set to 'Embedthis/Device'.
where	string	Conditional expression to select items for which to create metrics.

The metric namespace scopes the metrics and must be set to 'Embedthis/Device'. Other namespaces may be supported in the future.

The fields property contains an array with one or more metric definitions. Each definition may be either:

• An item attribute name which is used to identify the value AND to name the metric.
• A map of an item attribute name to a metric name.

For example:

{
    fields: ['temperature', 'status', 'speed']
}

This would create three metrics using the item's temperature, status and speed attributes. The metrics would take the same name.

Wheras:

{
    fields: [{Temp: 'temperature'}, {Online: 'status'}, {Level: 'speed'}]
}

This would create the metrics: Temp, Online and Level from the temperature, status and speed item attributes.

The dimensions property contains an array of dimensions that scope the metric. The elements of the dimensions array can be either field names or objects that map field names into a dimension name. If the values are quoted, they are used as literal values. If unquoted, they are regarded as database item field names.

For example:

process: {
    Fault:   { 
        sync: 'up' 
        metrics: [{
            namespace: 'Embedthis/Device',
            fields: ['temperature'],
            dimensions: [{}, {Device: 'deviceId'}]
        }]
    }
}

Where Expressions

The where property can be used to select matching device database items (rows) from which to create the metric.

The where query language is based on familiar Javascript expressions with some additional operators. Item attributes are expressed as variable names and literal values are expressed as JavaScript values.

For example: the expression:

error == "critical" && component == "PS1"

will select those items which have the error attribute set to "critical" and the component attribute set to "PS1".

For example:

{
    Store: {
        enable: 'both',
        sync; 'up',
        notify: 'default',
        metrics: [
            {
                namespace: 'Embedthis/Device',
                fields: [{CPU: 'value'}],
                where: 'key == "cpu"',
                dimensions: [{Device: 'deviceId'}],
                buffer: {count: 5, elapsed: 10},
            }
        ]
    }
}

See Expressions for more information on the expression syntax.

Metric API

Metrics can also be created in the Embedthis/Device namespace by using the Ioto Agent ioSetMetric API.

For example:

ioSetMetric("Temperature", 30.5, NULL, 0);

Then to read the metric in the agent:

double temp = ioGetMetric("Temperature", NULL, "average", 3660);

Displaying Metrics

Device apps can display metric data via graphical widgets

You can select from the following widget types:

• gauge
• graph
• table
• progress
• number
• leds

When creating or modifying a widget, you can select the data source to be either a database table item or a metric.

When selecting a metric, you enter the metric name, statistic and resource dimensions.

When selecting data directly from the database, you enter the database table model name, the model field (attribute) and a row selection expression.

Standard Metrics

The Ioto service computes standard metrics for each device cloud using the Embedthis/Ioto namespace.

Metric	Dimensions	Description
DevicesMade	Product:PRODUCT	Number of devices manufactured this month
DevicesClaimed	Product:PRODUCT	Number of devices claimed for cloud-based management this month
DevicesConnected		Number of devices connecting to the cloud this month
MsgIn		Number of messages received by the cloud
MsgOut		Number of messages sent by the cloud
Throttles		Number of times a device sending too much data was throttled
SyncIn		Number of database synchronization messages sent to the cloud
SyncOut		Number of database synchronziation messages sent to devices

Custom Metrics

Custom metrics created from device data streams are created using the Embedthis/Device namespace.