This tutorial will cover integrating the Bort SDK into a system running Android 10.
Create a Project and get a Project Key
Go to app.memfault.com and from the "Select A Project" dropdown, click on "Create Project" to setup your first project such as "smart-sink-dev".
Once you've created your project, you'll be automatically taken to an integration guide which includes your project key. Copy it to follow the rest of the guide.
Using a Git client, clone the
bort repository from:
Add this repo to your tree at
vendor/memfault/bort (i.e. add it to your repo
Apply AOSP patches using
bort_cli.py tool (requires Python 3.6+).
Decide on an application ID for the Bort application. By placing the application
under your domain, you may later upload it to the Google Play Store if
necessary. We suggest appending
bort to your
reverse domain name.
Patch the default application ID with your own:
This command will patch
bort.properties, setting the
We recommend placing the
includes below at the end of the respective
Makefiles. This is because
include directives are used to append to
variables in the build script; placing them at the end of the file reduces the
chances that subsequent lines in the
Makefile do not redefine those variables
and discard the effect of the
include. If it is not possible to place the
include at the end of the file, ensure that the respective variables are not
redefined (look for the
Add this line to your
device.mk file to get the components included in your
build; this appends to the
Add this line to your
BoardConfig.mk file to get the sepolicy files picked up
by the build system; this appends to the
You must set your Project Key in the Bort app. This is set in
MemfaultPackages/bort.properties; the app will not compile without this
We also recommend updating the other properties as necessary, for example, updating the SDK levels to match the API level of your OS and updating the build tools version to what is available in your environment.
If your devices will have
Google Mobile Services (GMS) and must
Compatibility Test Suite (CTS),
you may need to update the Bort target SDK version to match the API level of
your OS. This can be done by updating the
TARGET_SDK_VERSION property in
Additional settings can be configured via the Bort SDK over-the-air SDK settings system.
One setting that is worth calling out, is the option to capture "minimal" bug reports. If system load or bandwidth are concerns for your deployment, we recommend using minimal mode.
You must provide the Android SDK location for gradle. This can either be set
ANDROID_HOME env var, or by opening the project with Android Studio
(e.g. opening the root
build.gradle) which will auto-generate a
local.properties file with the
The bort app requires a Java keystore file so that the app can be signed.
Instructions on how to create a keystore in Android Studio can be found here. If you plan to update the app via the Play Store, you may wish to follow the additional instructions on that page.
- The key that is used to sign the Bort app must NOT be the platform signing key, otherwise updates to the Bort app may be rejected by the Play Store.
- The key must ONLY be used to sign the Bort app and no other apps. Special permissions are assigned to Bort based on the signing certificate.
Once you have a keystore, set up a
keystore.properties file and provide the
path to it via the
keystore.properties file must contain these properties:
MemfaultBort app is built using gradle. Building the release APK will
automatically invoke a task to copy the resulting APK and place it in the root
directory where it will be picked up by the AOSP build system.
This will create a signed
pem file is a public certificate used by the system to when enforcing the
MemfaultUsageReporter app is built using gradle. Building the release APK
will automatically invoke a task to copy the resulting APK and place it in the
root directory where it will be picked up by the AOSP build system.
bort_cli.py tool can be used to check for issues with the SDK
installation. To use it, install a build containing the Bort SDK on a device
that you wish to validate. Connect that device via ADB (verify via
adb devices) and run the script:
If you have multiple devices connected, use the
--device flag to specify the
target device. For more information on the different options, run the command
By default, the Bort SDK will only run after being explicitly enabled at runtime; this is to ensure no data is collected without user consent.
More information on enabling the SDK can be found in the Enabling the SDK at Runtime section of the Bort SDK documentation.
For the purposes of testing the SDK on a development device, the SDK can be enabled via ADB using the CLI tool:
Once the SDK has been enabled, you can manually trigger a bug report to be generated. Once generated, it will be automatically uploaded to Memfault:
More information on triggering a bug report can be found in Triggering A Bug Report Programmatically; more information on when bug reports are automatically captured can be found in Bug Report Capture Period.
Once the bug report has been generated, uploaded and processed successfully, you
will be able to find it in Memfault by navigating to the
Fleet > Devices view
and finding the device that uploaded the bug report.
If you do not see the bug report, you can check your project's
feature in the top right hand side of the
Issues page. This shows a list of
bug reports that were recently received and their processing status.
Here are some steps to assist in diagnosing some possible integration failures.
If the validation is failing due to missing system components, verify if the components are being built by searching the build artifacts.
If the binary is not being built, then verify the
- Is the bort
product.mkfile included in your
- Note that this include appends to the
PRODUCT_PACKAGESvariable: is this variable being redefined elsewhere via an assignment? (
:=) after including the
- Note that this include appends to the
- Is the bort
BoardConfig.mkfile being included in your
BoardConfig.mkfile? Similar to
PRODUCT_PACKAGES, verify that the
BOARD_PLAT_PRIVATE_SEPOLICY_DIRvariables are not being over-written. This could be solved by:
- Placing this include at the end of the file, or
- Ensuring subsequent assignments append to these variables (
If you have confirmed the binary is being built, the next step is to verify if the binary is inside the (system) image as expected. To do this, you can mount the system image and search inside it. You should see the following files included in the system image:
If these files are not present, then there may be an issue with your build process, you may be inspecting the wrong system image, or the SDK may be included in a different image.
If the SDK is enabled, a bug report is generated, but the logcat logs show that the upload has failed, then capture and upload a bug report manually over ADB so that we can assist with a detailed investigation:
Then navigate to
Issues in Memfault and upload the bug report via the
Manual Upload button in the top right hand side.
If you are viewing logs from a bug report and the timespan covered by the logcat logs or device timeline is less than expected, this may be because:
- The device recently rebooted and its non-persistent data was wiped.
- The system is logging a lot (being very "chatty") and is quickly filling up the buffer, causing older logs to be quickly evicted.
Logcat logs are collected by
dumpstate with the command:
This means that the bug report will collect whatever logs are available in the system buffer. Making the logs less chatty or increasing the size of the log buffer are two possible solutions.
Making the logs less chatty is likely to be the
more effective solution.
However, you can quickly evaluate effect of changing the size of the log buffer
that this setting is transient and will be lost when the system reboots. To
change the log buffer size permanently, use the