Metric Configuration

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

Metrics can have a few properties:

• a string_key which devices and APIs can use to identify the Metric. Note that string_keys are case-insensitive.
• a display_name (usually same as string_key) which will be used as a name across Charts, Alerts and Device Timeline.
• whether the data type is an INT (default), FLOAT, BOOL, or STRING.
• whether it is a favorite Metric, which will cause it to appear more prominently in a few places in the web app.
• for numeric metrics, the value range which informs charts and other components, and optionally controls filtering of values.
• whether a metric is set as Timeseries and/or an Attribute.

Memfault has default configurations for certain metrics that are well-known or built into our SDKs and may set configuration properties such as Timeseries, Attribute or value range for them upon creation.

info

Please contact us 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. 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	Devices are always allowed to change the value of this Attribute. This is the default. Example: Location of a mobile device that changes occasionally.
If not set	Devices can only set the value of this Attribute if it's currently unset. Useful to collect static device information the device has access to. Example: MAC addresses.
Never	Devices cannot set the value of this Attribute. Useful for Attributes that should only be managed manually or external systems. Examples: Installation sites, service-level agreement, RMA status.

Viewing an Attribute

There are two ways to view Attributes for a device:

1. using the web application
2. 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:

note

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:

1. using the Metrics APIs (MCU/Android/Linux)
2. using the REST API
3. using the web application.

note

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:

note

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

First Class Metrics

Memfault has certain first class metrics that will default to being an attribute. First class metrics are metrics that are deemed useful or necessary by the Memfault team and assigned certain defaults for ease of use. These metrics defined by the Memfault SDKs are as follows:

First Class Attribute Metrics List

String Key	Default Attribute	Default Timeseries
MemfaultSdkMetric_sdk_version	🟢 Yes	⛔ No
storage.data.bytes_free.latest	🟢 Yes	🟢 Yes
storage.data.bytes_used.latest	🟢 Yes	🟢 Yes
battery_soc_pct	🟢 Yes	⛔ No
uptime/uptime	🟢 Yes	⛔ No
Ncs_LteModemFwVersion	🟢 Yes	⛔ No
version.* (prefix)	🟢 Yes	⛔ No
sysprop.* (prefix)	🟢 Yes	⛔ No

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 if you need to re-create the metric with exactly the same name (often in the case of changing the Metric type).