Bort Lite Preview
The Bort Lite preview is designed to try out the
Bort SDK quickly and easily without
requiring a full installation. It contains a single Android application (APK)
that can be sideloaded onto any device that has adb
access without requiring
modifications to AOSP. It is not designed to be used in production. However, it
can still collect much of the data that the full SDK is capable of, including:
- Crashes (Tombstones, Java exceptions, ANRs, WTFs, Last KMSG)
- Metrics
- Log files (up to Android 12)
See Bort Features for a full breakdown of which features are available in Bort Lite versus the full Bort SDK.
Bort Lite releases are published to the Bort Lite Github repo, on the same cadence as Bort SDK releases. See the changelog in the main Bort repo.
1. Create a Project
Create or use an existing Memfault Organization. Once you have a Memfault Organization, create a new Android Project for Bort Lite.
2. Install Bort Lite
i. Enable adb
access on your Android device
To use adb
with a device connected over USB, you need to ensure two settings
are enabled on your Android device. Please reference the two links below to set
up your device:
ii. Connect the device to your computer
Connect the device to your computer using a USB cable. Verify that your device
is connected by executing adb devices
from the
$ANDROID_SDK/platform-tools/adb
directory. Your phone will pop up a banner
Allow USB Debugging. Check Always allow from this computer and press
Allow.
If properly connected, you'll see the device identifier listed under List of devices attached.
With some additional work, you can also connect to your device over Wi-Fi.
iii. Run the install script
Download bort-lite-release.zip
from the master branch of the
Bort Lite Github repo (you don't need
to check out the repo), and extract to a folder.
On macOS, open the Terminal, and run ./install-bort-lite.sh <project-key>
,
replacing <project-key
with the project key noted down earlier.
On Windows, open the Command Prompt, and run
install-bort-lite.bat <project-key>
, replacing <project-key
with the project
key noted down earlier.
This will install and enable Bort with the appropriate permissions granted!
3. Collect your first device metrics
Bort Lite will continually capture data, and will upload to the Memfault dashboard every 2 hours (when there is connectivity available). So by default, it may take up to 2 hours before seeing the device in the Memfault dashboard.
i. Trigger metrics collection manually
To see captured data immediately, or to trigger a manual data collection, Bort Developer Mode can be used. To enable Developer Mode:
adb shell am broadcast -a com.memfault.intent.action.DEV_MODE --ez com.memfault.intent.extra.DEV_MODE_ENABLED true -n com.memfault.bort.lite/com.memfault.bort.receivers.ShellControlReceiver
To collect metrics (once Dev Mode is enabled):
adb shell am broadcast -a com.memfault.intent.action.REQUEST_METRICS_COLLECTION -n com.memfault.bort.lite/com.memfault.bort.receivers.ShellControlReceiver
Consider enabling Server-Side Developer Mode as well, when using Bort Developer Mode.
Additional Information
Bort Lite is released as a single pre-signed binary for convenience — the
bort-lite.apk
. This is different to how the full Bort SDK is released (built
from source, signed with your certificate).
Bort Lite is limited in what operations it can perform:
- It can only be granted
development
permissions (i.e. cannot be granted anysignature
,privileged
orsystem
permissions, unless it is also available viadeveloper
). Most of the data collected by Bort is available with this permission, but not all. - It also cannot perform any operations which require a system UID (which would
need
Usage Reporter
, or one of the Bort system servicesMemfaultStructuredLogD
orMemfaultDumpster
) or modifiedSELinux
configuration. This includes full access to all sysprops. - It can not capture Android bug reports or continuous logs (these require a native system service).
- Performing an OTA via Memfault is not possible (this would need both
SELinux
changes, andsystem
permissions).
The bundled installation script grants all development
permissions at install
time, using the -g
argument to adb install
. It also whitelists Bort to run
in the background (using dumpsys deviceidle whitelist
), without which Bort
would not be able to do anything.
See Bort Features for a full breakdown of what features are available.