Guide: Sending a Logcat to Help Debug Your Favorite App
It’s happened to us all at one point or another. There’s no shame in admitting it. Sometimes, Android apps crash. Whether you’re using a completely stock device to run Google Maps or a highly-customized ROM with an Xposed module to enhance Google Hangouts, application crashes and other issues can occur and even become quite a hindrance. This is especially true in the development of smaller-scale tweaks and applications such as the many found on our website. When issues arise, one of the most constructive and helpful insights the user can lend the developer into the nature of the crash is through providing a Logcat. Although extremely helpful for developers, obtaining this information can seem somewhat daunting for a regular user.
Typically involving command-line tools through ADB, the Logcat is out of reach for many users who have little to no experience with the command line. However, the release of certain apps has eliminated, or at least greatly reduced, the involvement of ADB commands in retrieving and sending a Logcat, making doing so as easy as a few screen taps. In our never-ending mission to aid development for developers, here’s a beginner’s guide to teach users on how to send a Logcat.
What is a Logcat and how do we pull one?
A Logcat is an ADB Shell tool used to pull a log of all system events. This includes errors, warnings, stack traces, and general system occurrences. When an error occurs, key information pointing towards the source of failure is output through this log, making it a very useful tool for troubleshooting. Normally, these are pulled and filtered through ADB commands. However, apps such as aLogcat, Catlog, and our tool of choice for this article, Matlog, have saved users the effort by compiling these command tools into the GUI of a Play-Store-downloadable app.
As mentioned, Matlog is what we’re using for collecting Logcats. Chosen for its no-frills, yet user-friendly interface, Matlog was made by XDA Junior Member plusCubed and based on Nolan Lawson’s open-source app Catlog. Like Catlog, Matlog can be compiled from source, or downloaded for free from the Google Play Store. Although being rooted allows you to skip a step during setup, root access is not required to collect Logcats. If your device is not rooted, a single ADB shell command will grant the application access to read your device’s logs. Haven’t yet set up ADB on your machine? No problem, just follow these steps to get it up and running.
Setting up ADB
First, download the ADB binary straight from Google for your particular OS and extract it to a separate directory on your computer. Next, install the proper driver for your particular phone. Then, enable “USB Debugging” in Settings –> Developer Options. If you don’t see Developer Options, then you will need to enable it by going to Settings –> About Phone then tapping on Build number 7 times. Finally, ensure that ADB is working by starting a command prompt in the same directory as the ADB binary (right-click –> “open command prompt here”) and run the following command:
If you see your device’s serial number (and it doesn’t say unauthorized), you’re golden. If you see a pop-up on your phone asking you to grant your computer ADB access, then say yes. If you don’t see either happen, then try rebooting your computer/phone and re-plugging it into your computer. Otherwise, try re-installing the driver.
Setting up Matlog
Now that you’ve got ADB up and running (hopefully), all you need to do to enable Matlog the ability to capture Logcats is to issue the following command in an ADB shell. Again, if your device is already rooted, you do not need to run this command as this is only necessary for unrooted phones.
adb shell pm grant com.pluscubed.matlog android.permission.READ_LOGS
Once enabled and open, Matlog will display system events in real-time. You can tap the pause button to halt this, then tap the ellipses menu and select “clear” to rid the field of extraneous data. It’s recommended to do this in preparation of logging the malfunctioning app in order to cut down on log size. To shorten the steps, and therefore the log length even further, add the Matlog widget to your homescreen next to the crashing application in question, as shown to the right. In this instance, Apktool X is our malfunctioning app.
Tapping the widget allows you to name and begin recording a log. Then, simply reproduce the malfunction immediately after starting logging, which will fill the Logcat with pertinent information for your issue. Once the issue is reproduced, simply tap the widget again to complete the log recording.
Upon doing so, Matlog will open to the captured log. Tap the ellipses, and select “send” to email the log as an attached text file along with general device information. That’s it! Your Logcat has been successfully captured and sent to Professor Oak.
In my example above, I can tell that the reason Apktool X was crashing is because my device is unrooted. Doh! I should have fully read the article before trying to use the app.
That Was Too Easy
Of course, not all issues are that easy to capture. Sometimes issues dealing with booting, or issues that extend over longer periods of time may require different features of the app to capture. In such instances, you’ll want to let Matlog run in the background (don’t pause or clear it) and utilize the Log Level and Filter functions to parse through data.
Although not typically the only necessary method for gathering pertinent data – some situations require more context – each of these tools can be used on longer logs to sort and specify data for the developer. Naturally, this depends on the nature of the error and what the developer requests. To use either of these, simply run Matlog, reproduce your issue, navigate back into Matlog, tap the dot menu, and select one of these two sorting methods.
Another ADB command simplified by Matlog, the Log Level function can be used to view specific types of system events and messages. Below is a brief description of the various message types, as described by the Android Developers website and color coded to match Matlog’s labeling.
From lowest to highest priority:
- V: Verbose (General system events)
- D: Debug
- I: Information
- W: Warning
- E: Error
- F: Fatal
- S: Silent (Highest priority, on which nothing is ever printed)
The Log Level feature has a corresponding list of these messages, which can filter the log at each priority level. Selecting a log level will show only events at its own priority level and higher, facilitating easy identification and grouping of errors rather than requiring manually scrolling through numerous lines of text – which can sometimes be in the thousands – to do so.
Filters can also be employed to sort through log data. By initiating a keyword search, the user is enabled to see only messages which reference this keyword explicitly. Useful keywords may involve the name of the malfunctioning app or even the word “error” as it encompasses instances of the term on all priority levels, though it does not encompass all “Log Level” errors.
If you find yourself searching/filtering for certain keywords a lot when helping a developer debug an application (or if the developer has explicitly created a unique log event you can search for), then you can also save a filter that you can return to in the future. This is useful for when you know beforehand what you’re looking for, which if you’re working in conjunction with a developer, will happen quite often.
Ready to debug?
While you may not now be an expert in debugging Android apps, learning how to gather and send Logcats can make you a great resource for the developers of your favorite apps. Using Matlog, and the features of which outlined above, gathering, sorting, and sending pertinent information about a malfunctioning app has never been easier.
Have you used Matlog or another Logcat app? Did you find this guide helpful? Let us know in the comments below!