Doc: debugging with logcat
A bit about logcat
So for all of you who don't know about
adb logcat, it's probably time we talked about it.
When Android is running, it's generating all kinds of system messages. You see, programmers/developers can optionally output status information (or errors or debugging notes) in real-time to a system log, and Android itself sends all kinds of useful information out that way.
But if there's a running log going on at all times, how do you see it?
If you're connected via ADB (via a USB cable or whatever), try typing
adb logcat into your computer. The output to your terminal window, which can be interrupted with ^C (control + C), is a real-time look at Android's operation.
So, let's say you're experiencing a boot loop and want to get an idea of what's going on "under the hood". It can't hurt to peek with
adb logcat. Even if it just looks like gobbledygook, you can copy and paste the output (usually the errors will be obvious if you sit down and look-- stuff like "ERROR!!!!!" may appear) to a site like pastebin.com (although make sure that you're not pasting personal information such as local network addresses or anything sensitive, which occasionally will appear in the log). That way, you can show people the problem (via a link) for further discussion, debugging, etc.
Anyway, from now on-- instead of just saying "Help! I'm bootlooping!", maybe say "Help! I'm bootlooping, and here's a link to the logcat!"
Why is it called "logcat"? Here's my guess. In Unix (and Linux), there's a command called "
cat" (short for "concatenate files and print on the standard output" if you can believe it) that is used to view the contents of multiple files together, but it is often (ab)used to view the contents of a single file. So cat is kind of like a verb, in this context. You can try
cat a-file-name.txt from the Terminal of any Unix-like operating system (including Linux and OS X), and it'll spew out the file's contents to you. So "
logcat" is I guess "spew out (
cat) the contents of the log."
Bonus Command!: If you're using Linux or OS X and want to view a file from the terminal, but don't like how cat filename.txt spews the contents at you nonstop, try using
more filename.txt instead. I'll leave it to you to figure how it works.)
adb logcat offers extra functionality to filter logs based on priority. The usage is
adb logcat *:# where
# is one of the following.
V Verbose (show all possibly useless logs, default level) D Debug (show all reasonable debug logs) I Info (show expected logs for regular usage) W Warn (show possible issues that are not yet errors) E Error (show issues that have caused errors) F Fatal (show issues that are fatal to runtime and will often result in rebooting)
All priorities automatically include higher priorities, so
adb logcat *:W will show warnings, errors and fatal errors. When an app crashes, for example, you can usually use
adb logcat *:E to see the cause of the issue without having to look through irrelevant debug logging. However, when providing logs to developers make sure to include all logging (without any filtering tag) because debugging logs can often explain the error.
You can also filter by content. Let's say you want to collect all lines of the log that mention the term "Google". You can do this:
$ adb logcat | grep Google
This command takes the output of "logcat" (all the junk) and "pipes" it to the
grep command, which is used to search for "Google" and will only return lines that include it.
Note the pipe "|" character is not the same as a capital "I", a lowercase "L", the number "1", or a random graphical unicode glyph of a vertical line. On US keyboards, the pipe often created by holding down the Shift key and pressing the "\" key. The pipe character is used to take the output of one command and "pipe" it through to the input of the next command. In this case the output of
adb logcat becomes the input of
If you want to make your search case-insensitive, you can just add the
$ adb logcat | grep -i Google
This will return log lines that have "Google", "google", "gOoGlE" and any other combination of upper and lowercase characters.
adb logcat -C can be used to show logs with color to make them easier to read when viewing.
If you are not satified with the -C parameter, other possibilities are using external color logcat scripts or writing your own.
- Colored logcat by Jeff Sharkey (Git here, Blog post here)
- logcat-color by Marshall Culpepper (Git here)
If you find your screen is getting spammed with log messages you don't want, but you still need verbose logging, you can use
adb logcat -c to clear the log buffer. This will reset the log and only logs after the reset will be shown.
Logcat for Bugtracker
This will generate a logcat on your sdcard which you can then attatch to a bug you want to report.
- Open Console Application of your choice (CM comes with 'Terminal Emulator' preinstalled)
- Switch to root (type
suand confirm root access)
logcat -d -f /sdcard/logcat.log *:V
- Alternatively the radio buffer can be viewed with
logcat -b radio
-d makes it dump the logcat -f tell it where to save the log to *:V gets all Logs in Verbose mode
Run the logcat command after duplicating the issue you want to report.
Due to changes Google made in the internal APIs of Android starting with CM 10.0/Android 4.1 (Jellybean), you will need root permission for apps on the device to access the full logcat (the apps are now limited to only the logs generated by themselves). To do this with the built-in Terminal Emulator, you just need to type
su and hit enter before you run the logcat command.