✏ How to gather logs

So you’ve ran into a problem on your device - or you simply want to know what’s going on inside?
That’s great!

You may notice that there are many things missing here. If you know them, add them - this post is a #wiki .
If you are uncertain about changes you can discuss them first here.

On your device


On your PC with adb

  1. Setup adb.
    Windows: follow this guide.
    Linux: Simply install adb via your package manager. You should know how to do this. (I ran sudo apt install android-tools-adb on ubuntu)
    OS X: TODO
  2. Connect to your device.
    This can be done via USB (which is probably the easiest way - if you’re not using Windows. But no one is using Windows, anyway.) or via WifFi.
    If you want to use USB, simply take a cable and connect your phone to your PC.
    On your phone, you need to go to settings -> developer settings and enable USB debugging. (If you can’t see the menu for developer settings, you need to go to settings -> about phone and tap a few times on the build number.)
    If you want to use WiFi, install the app adbWireless on your phone (eg. from F-Droid) and start it. Then press the big button in the middle of the screen. Afterwards you’ll have to run the command listed in the app in your PC (adb connect <ip of your phone>).
    Run adb devices on your PC.
    You should see something like this:
List of devices attached 
<serial>      device

If it’s not device but unauthorized you need to unlock your phone and confirm the debugging for this PC and / or restart adbd as root on your PC. (For GNU/Linux this should be adb kill-server && sudo adb start-server.)
3. Start logcat.
logcat is a command that is available on every Android device (you can find a detailed manual here).
You can either start it from your device (if you’ve got a shell open - that is) or invoke it from the host via adb logcat. Try it - you’ll get lots of output. (Quit the program by sending it a SIGINT by pressing Ctrl-C.)

Parsing your logs

The interesting thing is finding out what’s actually relevant.

It doesn’t matter which way you’re gathering your logs - be it with an app on your device, adb or a plugin in your favourite IDE, the result you’ll getting is something like this:

P/Tag( PID): Message

P is the priority and according to adb logcat --help it’s either:

  V    Verbose
  D    Debug
  I    Info
  W    Warn
  E    Error
  F    Fatal
  S    Silent (supress all output)

You can filter your logs for priority and tag:

$ adb logcat <tag>:P

(If you’re using * as tag to get all tags, you may need to escape it as \* for your shell to ignore it.)

(My advice: If you’re not looking for something specific, simply save all logs (add >> filename.log after your command) to your PC and filter afterwards - it’s better got catch too much than missing the important things.
But if you just want to debug one app, you can filter for your tag, of course.)

Be aware that priority and tag are fixed for a built app, but message and PID may change (in relation to use-case, data or install time).

You can try looking through the logs, manually, but they’re quite big.
I prefer using grep:

$ grep -C 20 -i thingtosearchfor filename.log

This will search for all occurrences of thingtosearchfor (ignoring upper or lower case) in filename.log and give you 20 lines of context around that.

What to look for

That’s entirely up to you.

But there are a few common scenarios.

an app is crashing

You’ll want to search for a Java stacktrace. They look like this:

TypeOfException: a message that is more or less helpful
    at android.somepackage.SomeClass.someMethod(SomeClass.java:1234)
    at org.example.crashingapp.SomeClass.someMethod(SomeClass.java:23)
    ... 10 more

(This is just a short one.)

You need to know what you’re looking for.
If you think, it’s a problem with the ROM you’re running, you need to look at the higher methods.
If you think, it’s a problem with an app, you need to look in the middle.
(That’s just some general advice, don’t take my word for it.)

But the problem is not only with understanding the stacktrace, the problem is also with finding them. And that depends on the app.
If the app in question has no error handling at all, Android will close it and display a dialog stating that. It logs the error:

E/AndroidRuntime( <PID of the app_process of the app>): 

If the app does some error handling, it may log the stacktrace itself (the tag and priority might differ but the PID will be the same) or even discard it entirely.