Metrics and Attributes
Metrics are a way to proactively monitor any smart device. They power parts of our Device view such as Device Attributes and the Timeline. You can use them to monitor your releases and view data-driven device and fleet-level Metrics, like battery health, connectivity, and more using Memfault's Metrics features: Metric Charts and Alerts.
Metrics can be marked as Timeseries as well as Attributes, and each option enables a different set of features in the Memfault app.
Defining a Metric
Metrics can be added manually but are also created automatically when devices report them from the field.
Automatically from Memfault's SDK
Here are some useful links if you're looking to enable Metrics collection from your devices using our SDKs:
- for MCU: Collecting Device Metrics using our MCU SDK
- for Android: Bort SDK Built-In Metrics, Bort Custom Metrics APIs
- for Linux: Linux Metrics
From the Memfault app
You can view all defined Metrics by going to Project Settings -> Metrics.
The Metrics view under Project Settings
Metric can have a few properties:
- a
string_key
which devices and APIs can use to identify the Metric - a
display_name
(usually same asstring_key
) which will be used as a name across Charts, Alerts and Device Timeline - whether the data type is an
INT
(default),FLOAT
,BOOL
, orSTRING
- whether it is a
favorite
Metric, which will cause it to appear more prominently in a few places in the web app - the value
range
which informs charts and other components, and optionally controls filtering of values.
Please contact us at support@memfault.com if you want to use a custom name
(display_name
) that is different from the technical id (string_key
) reported
by the devices for a metric across Charts,
Alerts and Device Timeline.
Timeseries
By marking a Metric as a Timeseries you'll be able to use it in
Metric Charts and Alerts.
You'll also be able to use them to
search for devices with a
time constraint (e.g. battery_level > 90 anytime last week
).
To mark a Metric as a Timeseries, go to Project Settings -> Metrics and click Edit on the Metric you're interested in. Then check the Timeseries checkbox.
Attributes
You can store custom Attributes for each of your devices to build a device registry or to manage inventory.
By marking a Metric as an Attribute it will be shown in the Attributes tab on device pages. You'll also be able to search for devices by Attributes on the device list page.
Defining an Attribute
In Project Settings -> Metrics you'll be able to mark specific Metrics as Attributes. Metrics reported by devices are automatically marked as Attributes*. You can configure this by clicking Edit on a Metric you're interested in, or by creating a new Metric with the Attribute feature enabled.
Device Write Policy
Attributes have a device_write_policy
property that controls under which
condition a device can change its value. This does not affect the ability to set
a value manually on the device page.
Writable |
|
If not set |
|
Never |
|
Viewing an Attribute
There are two ways to view Attributes for a device:
- using the web application
- using the REST API.
Using the web application
Find the device you want to view the Attributes for (for example by browsing your devices on the Devices page) and select the Attributes tab. You'll see all the properties known for this project and the respective value for the device you're currently looking at.
The device detail page and its Attributes tab
Using the REST API
Below is an example of how Attributes can be read using the Project Key and the REST API:
Be sure to replace ${MEMFAULT_ORG_TOKEN}
with an
Organization Auth Token and
${ORG_SLUG}
/ ${PROJECT_SLUG}
/ ${DEVICE_SERIAL}
if re-using the example
below.
curl --user ":${MEMFAULT_ORG_TOKEN}" --location --request GET \
'https://api.memfault.com/api/v0/organizations/${ORG_SLUG}/projects/${PROJECT_SLUG}/devices/${DEVICE_SERIAL}/attributes'
The response will be JSON-encoded data, example below:
{
"data": [
{
"custom_metric": {
"data_type": "INT",
"description": "",
"display_name": "",
"favorite": false,
"id": "5e8b5af5-c686-43a7-8ba4-7878f7f9105e",
"range_violation_behavior": "accept",
"range": {
"max_inclusive":true,
"min_inclusive":true,
"min":null,
"max":null
},
"string_key": "TimerTaskCpuUsage",
"device_write_policy": "writable"
},
"state": {
"created_date": "2021-09-20T13:25:37.517191+00:00",
"time": "2021-09-20T14:15:17.586209+00:00",
"updated_date": "2021-09-20T14:15:17.611765+00:00",
"value": 679
}
},
...
]
}
You can select individual Metric values by appending a URL query parameter:
https://api.memfault.com/api/v0/organizations/${ORG_SLUG}/projects/${PROJECT_SLUG}/devices/${DEVICE_SERIAL}/attributes?q=TimerTaskCpuUsage`
Only Metrics with matching string_key
will be returned (wildcard *
supported).
Setting an Attribute
There are three ways to write an Attribute:
Because devices can update Attributes, anyone who holds your Project Key can write or overwrite these Attributes.
Using the REST API
Below is an example of how Attributes can be set using the Project Key and the REST API:
Be sure to replace ${DEVICE_SERIAL}
and ${YOUR_PROJECT_KEY}
below with the
device you want to update and your
Project Key, respectively.
curl --location --request PATCH \
"https://device.memfault.com/api/v0/attributes?device_serial=${DEVICE_SERIAL}" \
--header "Content-Type: application/json" \
--header "Memfault-Project-Key: ${YOUR_PROJECT_KEY}" \
--data-raw '
[
{"string_key": "ProductName", "value": "SmartWatch"},
{"string_key": "ModelColor", "value": "Blue"}
]
'
Using the Web Application
Visit the respective device page as described in Viewing an Attribute. Click on the pencil icon next to the value, enter the new value, and finally Save it.
Editing an Attribute via the web application
Searching Devices by Attributes and Timeseries
You can search devices by Attributes and Timeseries. Visiting the Devices page, open the Filter panel.
To filter by Attributes, add a Custom Attribute filter.
Searching devices by Attribute
To filter by Timeseries, add a Historical Data filter and select Timeseries.
Searching devices by Timeseries
Float/Integer Range
For numeric metrics, the valid range can optionally be specified. For example, for a floating point metric that represents a percentage, you would specify a range of 0 to 100 and make both the start value and end value inclusive:
When specifying only the start of the range, only values greater than (or equal if inclusive) to the start value will be accepted. Conversely, when specifying only the end of the range, only values less than (or equal if inclusive) to the end value will be accepted.
Ingress Filtering
The effect of the range is controlled with the "Ingress Filtering" setting:
- "Accept all values": all values are accepted, regardless of whether they are within the range or not. This is the default for new metrics. The range may be used for display purposes in the future.
- "Accept only values within range": only values within the range are accepted. Values outside the range are ignored for most features in Memfault. See the following table for more details.
Effect of "Ingress Filtering" on out-of-range values, per feature
Feature | Accept all values | Accept only values within range |
---|---|---|
Fleet-wide Metrics charts | 🟢 Included | ⛔ Ignored |
Device Search | 🟢 Included | ⛔ Ignored |
Device-Threshold Alerts | 🟢 Included | ⛔ Ignored |
Fleet-Threshold Alerts | 🟢 Included | ⛔ Ignored |
Device Timeline: Heartbeat data | 🟢 Included | ⛔ Ignored |
Device Timeline: High Resolution Telemetry (HRT) | 🟢 Included | 🟢 Included (known issue) |
MCU Device Metrics Charts | 🟢 Included | 🟢 Included (known issue) |
Raw Data Exports | 🟢 Included | 🟢 Included |
Quotas
You're only allowed to use a limited amount of Device Attributes or Timeseries. If you exceed the quota, you need to turn off the respective aspect for a different Metric.
To see your quota usage, open your Project's settings page and click on the Quotas tab.
Apart from being limited by quotas, the ingestion of Metrics may be rate-limited. Avoid sending data more than once per hour per device.
To adjust which metrics count against the quotas, open project settings and click on the Metrics tab. Clicking on an individual metric opens the edit window where settings can be adjusted, including how the metric counts against quotas:
Archiving & Unarchiving Metrics
If a metric is no longer needed, it can be archived by navigating to Project Settings -> Metrics, clicking on the specific metric, and then clicking the Archive button.
To restore a metric, scroll to the bottom of the list of metrics, click on Show archived metrics, and click Restore next to the metric you would like to restore.
Troubleshooting
A Metric already exists with the same name
When attempting to create a Metric and one with the same name already exists, regardless of whether it is active or archived, an error will take place.
Contact us at support@memfault.com if you need to re-create the metric with exactly the same name (often in the case of changing the Metric type).