PhoneHome: Remote logging for Android
December 5th, 2013
Building Hoot showed Christina and I the ugly side of Android fragmentation. Hoot is currently running on over 1600 different device models on five different versions of the Android OS (>= 4.0), and it makes extensive use of the hardware: multiple cameras, the light sensor, and the orientation sensor. Unsurprisingly, given the number of different configurations, we’ve seen some weird behavior: crashes, incorrectly-rotated videos, and even videos recorded in sixplicate!
In the beginning, our patient friends handed over their phones for debugging; we’d plug the phones into our laptops and either step through Eclipse’s debugger or print useful information to logcat, Android’s logger. Though it was helpful, it didn’t scale: our friends collectively had fewer than 20 of the 1600+ models we eventually saw.
We looked at services that read, save, and send logs from phones remotely, but they required more effort from end users than we wanted to put our friends through – let alone users we didn’t know. As of Android Jelly Bean, reading from logcat requires root access, which is a permission we didn’t want to require in the public app either.
Instead, we built PhoneHome. PhoneHome retrieves Hoot’s logs from mischievous devices without asking anything from the user. We define the logs we want by specifying device model, OS version, app version, and username on the backend. If a user matches a criteria set, Hoot sends its logs to us, so we can see exactly what happened when the devices misbehaved.
Here’s how it works:
Configure PhoneHome in the
onCreate() of your main activity (the one associated with the
android.intent.action.MAIN intent). PhoneHome must be configured initially, but it can always be changed or turned off later.
The most important configuration options are
enable() toggles log flushing to the backend, and
logSink() specifies how the logs are flushed. When a batch of logs is ready to be flushed, it’s passed to the
flushLogs() method of the PhoneHomeSink object specified in
It’s important to differentiate between logging to logcat (normal logging behavior) and flushing a batch of logs. If a log event goes through PhoneHome and meets the parameters specified in
productionLogLevel(), it’s immediately logged to logcat locally and is added to the current log queue that’ll be sent to your PhoneHomeSink, where it is later flushed to your sink.
Here’s an example configuration:
Using PhoneHome’s logger instead of Android’s system logger is easy.
First, here’s a typical pattern that uses Android’s system logger:
PhoneHome’s logger works similarly. Construct a PhoneHomeLogger instance for each TAG. (Now, you don’t have to type the first parameter over and over.) Then, use the PhoneHomeLogger instance as you would Android’s system logger:
To avoid collecting unnecessary logs (and save your users’ battery and data plans!), we recommend checking if a user matches a particular criteria set before flushing logs. We’ve included an example of this in the sample app and backend in the GitHub repository. Once you’ve determined whether a user should phone logs home, enabling, disabling, or re-enabling PhoneHome is as easy as:
When a batch of logs is ready, it’s passed to your PhoneHomeSink object. From there, you choose what to do, though typically, we think you’ll want to send it to your backend with a network request. Since there isn’t a standard Android networking library and backend APIs are different, you’ll want to work it into your existing patterns for network requests and API calls. Here’s an example of how you might do with this with the AndroidHttpClient
We recommend specifying the device configuration associated with log events to simplify deduping. One strategy is sending along the Android device model, SDK version, app versionCode, username, and/or other identifying information with the log events. After all, logs from a misbehaving device aren’t very helpful if you can’t tell from which device they came!
Our example app and backend show one way to send device information with each request.
We built a barebones, Bootstrap’d web dashboard to display logs we collected, but you can just as easily look at the lines, by user and device, in your database. In the sample backend application, the logs are stored in the
Similarly, you could set user-log configurations using our simple web form or by editing the database directly.
We’ve open-sourced PhoneHome’s Android pieces, providing hooks for you to turn on/off logging and log sending. We’re not providing a backend library, but we are including a sample backend implementation that might help as you add PhoneHome to your Android app.
Happy logcatting! Please let us know what you think!