Memfault has support for various built-in AOSP metrics, like battery health, wakelock counts, foregrounded apps and so on.
Aside of the built-in metrics, it is also possible to define custom ones. In this guide we describe step-by-step how to add custom metrics to periodically collect the RSSI (Received Signal Strength Indicator), ambient light sensor measurements and the available disk space of our fictive devices. In Memfault's UI, the data that gets collected from each device over time, is visualized in graphs in the Timeline:
- RECOMMENDED: Define your custom tags and generate helper methods. Define tags
mflt_prefix. AOSP-built apps should define an
EventLog.logtagsfile in their root directory and add that entry to their
- REQUIRED: Call the
EventLogAPI to log events. If you compiled a custom
EventLog.logtagsfile, use the generated Java APIs. Otherwise use
EventLogdirectly with an integer tag in the range of 1000000-2000000, or a custom
mflt_-prefixed tag defined in
/system/etc/event-log-tags(which is generated from
When Memfault receives a bug report containing those custom events, they will be
displayed in that Bug Report's timeline under
The Android SDK contains an API called EventLog. As per its documentation, this API is intended to record system-level diagnostics.
The heart of the API looks like this:
EventLog.writeEvent(int tag, ... value)
where the dots can be
string, etc. We won't be using this API
directly, but a generated helper class. More on that later.
tag argument is a unique code or "key" that is used to be able to identify
the type of event. In this guide, we will be logging RSSI, ambient light level
and free disk space. We will use a separate tag for each.
Note that the tag code space is shared with the whole system. Many codes are already used for AOSP-internal purposes. Tags 1000000-2000000 are available for vendor/OEM/3rd party use.
Tags can also be given string names, through "
.logtags" files that map the tag
code to the tag name, as well as define the expected value type(s). More on that
To see what tags are being used on your system, run
adb shell cat /system/etc/event-log-tags to dump out the list of known tags.
The Memfault UI will automatically visualize data that is logged for named tags
starting with the prefix
This requires adding the tag code, tag name to a
.logtags file. These
.logtags files are merged together to generate the
/system/etc/event-log-tags file that is baked into the ROM and is therefore
only an option for apps that are built as part of the AOSP build.
Alternatively, for apps that are not built as part of the AOSP build, "anonymous
tags" can be used. If a tag code is used, but the tag code is not present in the
/system/etc/event-log-tags file, we call it an "anonymous tag". The data will
still be visualized, but in the UI, it will be labelled with the tag's code
instead of the human-readable tag name.
The AOSP comes with tooling for defining EventLog tags, generating Java helper
classes and getting the tags merged into
/system/etc/event-log-tags. Create a
EventLog.logtags in your app's source directory:
At the top, specify the Java package of your application. In the next sections, we will get back to this.
The rest of the file contains one tag definition per line. Each starts with the
tag code, the tag name and finally the value name and data type. For this guide,
we use the
int data type (
Tag names (minus the
mflt_ prefix) show up in the Memfault UI. For example,
mflt_disk_space_free will be displayed as "Disk Space Free". See also
the screenshot at the top of this page.
Even though values must be named, the value names are currently not used by the Memfault UI.
For more details on the syntax, we recommend reading the commentary in this .logtag file in the AOSP source code.
EventLog.logtags file (for AOSP-built apps)#
The AOSP build system has built-in support for
.logtags files, taking care of
It will merge our custom tags from the
It will generate a
.javasource file with a helper class
com.acme.myapp.EventLog(named based on the logtags file name and
option java_package ...).
To build the
EventLog.logtags file, add a new
java_library to your app's
Android.bp file and also add this new target is added to the
list of your app:
Based on the
EventLog.logtags file, the AOSP build system generates a Java
class that looks like this:
The helper class has methods for each of the tags, ensuring the correct tags codes are used and the values are of the expected types.
For apps that are not built as part of an AOSP build, we need to run the code
generator script to generate a Java helper class from the
- Clone the AOSP repo that contains the generator script:
- Run the code generator script:
As of March 2020, the script was not yet Python 3.x compatible and required Python 2.x to run.
We recommend running the script as part of your app's Gradle build.
Now that we've defined tags for our metrics and have generated the helper class, let's instrument our app's code.
In our application, we have a long running
Service that has access to the data
we want to collect. The goal is to periodically collect the metric data for the
past hour and log it to the
Now build AOSP and/or the app, install it and let it run for a while to collect your custom metrics data!
The metrics data is automatically emitted into a Bug Report. For testing
adb bugreport to
generate a Bug Report locally.
Upload the resulting
bugreport-*.zip file to Memfault, by going into "Issues"
=> "Manual Upload".
Once the Bug Report is processed, go to "Devices" => Select your Device => "Timeline". A new group called "EventLog" should appear in the Timeline view. Expand the group to see "Rssi", "Ambient Light" and "Disk Space Free".
I don't see any rows for my custom metrics in the Memfault UI, how to debug this?
- Try running
adb logcat -b events. This wil print all collected data. If your events are not present there, double check that the
EventLog.write...calls actually happen.
- Make sure the tag names are prefixed with
mflt_(lowercase). Data is only shown for named tags starting with the
mflt_prefix or for anonymous tags that are not added to
- Ensure EventLog calls have only 1 value argument. Multiple values per tag are currently not supported.
- Ensure calls for a given tag must use the same type. Changing the value type from one call to the next for the same tag is not supported.
- Try running