Skip to main content

Android Built-in Metrics

The Bort SDK contains built-in support for collecting various types of metrics from Android devices.

Some are automatically collected, and some require configuration in the Memfault dashboard.

To record custom metrics, see the Reporting APIs.

info

Be sure to configure which metrics you would like to be Timeseries and Attributes in the Metrics Dashboard.

Collected via HRT since Bort 4.5.0

Since Bort 4.5.0, battery metrics on timeline are displayed using High-Resolution Telemetry (note: this is behind a feature flag which is being rolled out progressively to devices running 4.5.0 or higher).

Several new metrics were added to timeline as part of this change - these are only available when collecting via HRT:

  • Wifi On
  • User (current active user on multi-user devices)
  • Foreground User (current foreground user on multi-user devices)
  • Job (adds job identifier)
  • Package Install (shows all PackageManager installs, with package and version)
  • Package Uninstall (show all PackageManager uninstalls, with package and version)

Collected Since Bort 3.0

Bort collects metrics from the Android batterystats subsystem. This includes data from many components which may affect battery usage (Radio, Wifi, Bluetooth, Screen, CPU, GPS), in addition to statistics about the battery itself.

These metrics are displayed on the device timeline:

And several summary metrics are also available. Each metric is listed below, noting the batterystats output code that it is derived from (they are defined in the batterystats source):

  • audio_on_ratio: percentage of time (0.0-1.0) audio was switched on (see batterystats a).
  • battery_discharge_rate_pct_per_hour_avg: percentage drop (-0-100) per-hour, when discharging.
  • battery_health_not_good_ratio: percentage of time (0.0-1.0) when the battery health was not "good" (g) (see batterystats Bh).
  • battery_level_pct_avg: mean battery level (0-100).
  • bluetooth_scan_ratio: percentage of time (0.0-1.0) with bluetooth LE scanning active (see batterystats bles).
  • cpu_running_ratio: percentage of time (0.0-1.0) CPU was running (see batterystats r).
  • cpu_resume_count_per_hour: number of times per hour CPU became active (see batterystats r).
  • cpu_suspend_count_per_hour: number of times per hour CPU became inactive (see batterystats r).
  • cpu_wake_count_per_hour: number of individual CPU wakeups (see batterystats wr).
  • doze_full_ratio: percentage of time (0.0-1.0) spent in full Doze mode (see batterystats di).
  • doze_ratio: percentage of time (0.0-1.0) spent in any (full or light) Doze mode (see batterystats di).
  • gps_on_ratio: percentage of time (0.0-1.0) GPS was switched on (see batterystats g).
  • max_battery_temp: maximum battery temperature (°C x 10) during the period (see batterystats Bt).
  • phone_radio_active_ratio: percentage of time (0.0-1.0) the phone radio was active (see batterystats Pr).
  • phone_scanning_ratio: percentage of time (0.0-1.0) the phone was scanning (see batterystats Psc).
  • phone_signal_strength_none_ratio: percentage of time (0.0-1.0) the phone signal strength was "none" (0) (see batterystats Pss).
  • phone_signal_strength_poor_ratio: percentage of time (0.0-1.0) the phone signal strength was "poor" (1) (see batterystats Pss).
  • screen_on_ratio: percentage of time (0.0-1.0) the screen was on (see batterystats S).
  • screen_brightness_light_or_bright_ratio: percentage of time (0.0-1.0) the screen brightness was "light" (3) or "bright" (4) (see batterystats Sb).
  • wifi_on_ratio: percentage of time (0.0-1.0) Wifi was on (see batterystats W).
  • wifi_radio_active_ratio: percentage of time (0.0-1.0) Wifi was on (see batterystats Wr).
  • wifi_running_ratio: percentage of time (0.0-1.0) Wifi was on (see batterystats Ww).
  • wifi_scan_ratio: percentage of time (0.0-1.0) Wifi was scanning (see batterystats Ws).
  • wifi_signal_strength_poor_or_very_poor_ratio: percentage of time (0.0-1.0) Wifi signal was "poor" (1) or "very poor" (0) (see batterystats Wss).

These metrics would be good candidates for Timeseries metrics, to monitor fleet performance over time and find outlier devices.

Battery Summary Metrics​

Supported Since Bort 4.8.0

Bort 4.8.0 supports collecting new types of battery metrics, which show a summary of battery usage during the collection period:

  • screen_off_battery_drain_%/hour: battery drain rate while the screen was off - useful for isolating battery drain rate from screen usage (0-100% per hour).
  • screen_on_battery_drain_%/hour: battery drain rate while the screen was on (0-100% per hour).
  • estimated_battery_capacity_mah: battery capacity reported by Android.

The above metrics are available for use as timeseries metrics.

Additionally, per-component battery usage is displayed on timeline. The usage (in % per hour) for component app which used >= 0.01% is shown as follows:

  • This is shown in the Battery Usage %/hour swimlane as shown in the screenshot, with separate entries for each component. This includes both Android OS components (e.g. cell, idle, android, screen, bluetooth, gnss) and applications (e.g. com.google.android.youtube, com.android.vending, com.whatsapp).
  • These per-component metrics are only displayed on timeline - they are not available as timeseries metrics.

Device Temperatures​

Collected Since Bort 4.0

Bort regularly collects several device temperature metrics, from the HardwarePropertiesManager:

  • CPU
  • Device Skin

These are reported with min/max/mean values each hour. Note that each device has a different collection of sensors - an example device with one device skin sensor and two CPU sensors might have a set of metrics like this:

  • temp_skin_0.max
  • temp_skin_0.mean
  • temp_skin_0.min
  • temp_cpu_0.max
  • temp_cpu_0.mean
  • temp_cpu_0.min
  • temp_cpu_1.max
  • temp_cpu_1.mean
  • temp_cpu_1.min

These metrics would be good candidates for Timeseries metrics, to monitor fleet performance over time and find outlier devices.

Storage Usage​

Collected Since Bort 4.3.0

info

Before Bort 4.3.0, these metrics were collected differently (as storage.primary.*).

Bort regularly collects device storage usage metrics from the Environment.getDataDirectory (getFreeSpace/getTotalSpace):

  • storage.data.bytes_free
  • storage.data.bytes_total
  • storage.data.bytes_used
  • storage.data.percentage_used

These metrics would be good candidates for Timeseries metrics, to monitor fleet performance over time and find outlier devices.

Installed App Versions​

Collected Since Bort 4.0

Bort can collect installed app versions as metrics. These can be configured on the Memfault Settings Dashboard, on the Data Sources tab, by entering package names to collect:

Wildcards can be used, to collect multiple apps sharing the same package root.

Each collected version is stored as a metric, prefixed with version.:

These metrics would be good candidates for Attributes, to enable e.g. searching for devices with a given app version installed, or checking the installed versions on a specific device.

System Properties​

Collected Since Bort 4.0

Bort can collect Android System Properties. These can be configured on the Memfault Settings Dashboard, on the Data Sources tab, by entering each property to collect:

Each collected property is stored as a metric, prefixed with sysprop.:

These metrics would be good candidates for Attributes, to enable e.g. searching for devices with a given system property, or checking the properties for a specific device.

info

persist.sys.timezone is collected by default, (along with ro.build.type). This is used in the Memfault dashboard to enable browsing in the device's time zone.

Connectivity Metrics​

Collected Since Bort 4.4.0

Bort collects metrics describing connectivity changes on the device:

  • connectivity.type: current primary connectivity: NONE, WIFI, CELLULAR, ETHERNET, or UNKNOWN. Aggregated metrics for each type e.g. connectivity.type_CELLULAR.secs/hour.
  • airplane_mode: tracks whether airplane mode is enabled.
  • connectivity.validated: tracks whether current connectivity has been validated for internet.
  • connectivity.captive_portal: tracks whether device is connected to a captive portal.

Fleet Sampling Aspect Metrics​

Collected Since Bort 4.5.0

info

These are only collected for customers using Fleet Sampling.

HRT metrics show the active Fleet Sampling resolution for each aspect, over time. These can be seen on the device timeline for devices with the debugging aspect enabled:

  • debugging.resolution: OFF / NORMAL.
  • monitoring.resolution: OFF / NORMAL.
  • debugging.resolution: OFF / NORMAL.

These are also reported as heartbeat metrics, which can be used as device attributes or timeseries metrics (and seen with hourly resolution on timeline for devices with the monitoring aspect enabled):

  • debugging.resolution.latest: OFF / NORMAL.
  • monitoring.resolution.latest: OFF / NORMAL.
  • debugging.resolution.latest: OFF / NORMAL.