Mastering ADB logcat: Options, Filters & Advanced Debugging Techniques

Examples and Illustrations for Mobile App Testers and Developers

In the fast-paced world of Android development, timely and accurate bug reporting can make all the difference. For developers and testers, the ability to quickly capture, filter, and analyze logs is essential to maintaining robust and reliable applications. In this article, we dive into the powerful capabilities of ADB logcat, explore advanced filtering and buffer management techniques, and share best practices to ensure that every bug report is backed by actionable insights.

Introduction

When an app behaves unexpectedly or crashes on startup, there’s no better ally than ADB logcat. This command-line tool not only provides a real-time stream of system and application logs but also supports powerful filtering options that help isolate the root cause of issues. Whether we’re capturing logs for a bug report or dissecting a crash dump on a disconnected device, mastering logcat is key to efficient debugging.

In this article, we walk through a real-world scenario — from installing a new APK on an emulator to capturing, filtering, and archiving logs. We’ll elucidate how to leverage logcat’s buffers, utilize filtering options like grep and regular expressions, and apply techniques that ensure you never miss the critical clues hidden in your logs.

Why ADB logcat Matters

Every time an Android device logs an event — whether it’s an internal system notification, an app-level debug message, or a critical crash — the adb logcat utility records that information in a buffer. These logs:

• Document the System State: Timestamps, log levels, and stack traces provide a chronological narrative of what transpired.
• Guide Debugging: Detailed error messages and exception traces can pinpoint the origin of a problem.
• Support Bug Reporting: Supplementing our bug reports with logcat outputs, screenshots, and videos creates a compelling case for developers to act on.

For example, after installing a freshly built APK, we might encounter an immediate crash. Capturing the log output at that moment — and filtering for crash details — can help developers quickly diagnose and fix the issue.

Capturing Logs for Bug Reports

Imagine this workflow:

1. Install the APK:

% adb devices 
List of devices attached
emulator-5554 device  

% adb install /path/to/myapp.apk
Performing Streamed Install
Success

2. Capture a Crash Screenshot:

% adb shell screencap -p > ~/Desktop/app_crash.png

3. Retrieve Real-Time Logs:

% adb -s emulator-5554 logcat

When the app crashes on launch, the log output can be overwhelming — containing both historical and current data. This is where advanced filtering becomes essential.

Managing Logcat Buffers

Android devices use a circular buffer to store logs. By default, the buffer size is often around 256 KB — extended to 1 MB with Developer Options enabled. This means:

• Historical Data: The buffer contains a snapshot of recent events, which is critical when a device is disconnected after a crash.
• Buffer Limits: Once full, new logs push out older entries. Acting quickly to capture logs after a crash is vital.

You can adjust the logger buffer size in the device settings under System > Developer options > Logger buffer sizes.

If your investigation requires crash-specific logs, use the crash buffer:

% adb logcat -b crash

This command isolates crash logs, such as:

% adb logcat -b crash
--------- beginning of crash
02-14 16:20:34.060  3753  3753 E AndroidRuntime: FATAL EXCEPTION: main
02-14 16:20:34.060  3753  3753 E AndroidRuntime: Process: com.myapp.android, PID: 3753
02-14 16:20:34.060  3753  3753 E AndroidRuntime: java.lang.RuntimeException: Unable to create application com.myapp.android.App: com.getkeepsafe.relinker.MissingLibraryException: librealm-jni.so
02-14 16:20:34.060  3753  3753 E AndroidRuntime:  at android.app.ActivityThread.handleBindApplication(ActivityThread.java:6764)
02-14 16:20:34.060  3753  3753 E AndroidRuntime:  at android.app.ActivityThread.-$$Nest$mhandleBindApplication(Unknown Source:0)
02-14 16:20:34.060  3753  3753 E AndroidRuntime:  at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2133)
02-14 16:20:34.060  3753  3753 E AndroidRuntime:  at android.os.Handler.dispatchMessage(Handler.java:106)
02-14 16:20:34.060  3753  3753 E AndroidRuntime:  at android.os.Looper.loopOnce(Looper.java:201)
…
02-17 13:07:45.047 10818 10818 E AndroidRuntime: FATAL EXCEPTION: main
02-17 13:07:45.047 10818 10818 E AndroidRuntime: Process: com.myapp.android, PID: 10818
02-17 13:07:45.047 10818 10818 E AndroidRuntime: java.lang.RuntimeException: Unable to create application com.myapp.android.App: com.getkeepsafe.relinker.MissingLibraryException: librealm-jni.so
02-17 13:07:45.047 10818 10818 E AndroidRuntime:  at android.app.ActivityThread.handleBindApplication(ActivityThread.java:6764)
02-17 13:07:45.047 10818 10818 E AndroidRuntime:  at android.app.ActivityThread.-$$Nest$mhandleBindApplication(Unknown Source:0)
02-17 13:07:45.047 10818 10818 E AndroidRuntime:  at android.app.ActivityThread$H.handleMessage(ActivityThread.java:2133)
02-17 13:07:45.047 10818 10818 E AndroidRuntime:  at android.os.Handler.dispatchMessage(Handler.java:106)
…
02-17 13:07:45.047 10818 10818 E AndroidRuntime:  ... 9 more
^C
 ~

Once captured, we can redirect the output to a file:

% adb logcat -b crash > logcat.txt
^C
 ~
% pwd
/Users/lanabegunova
 ~
% ls
...
Desktop  Postman   logcat.txt
...
 ~
% open logcat.txt
 ~

This log file can be attached alongside screenshots and videos in our bug report.

Filtering Techniques and Commands

Advanced filtering allows us to extract the precise information we need:

• Using grep for Specific Apps:

adb logcat | grep 'myapp'

• Filtering Multiple Patterns with Extended Regex:

adb logcat | grep -E '(myapp1|myapp2)'

• Concurrent Output with tee:
• If you want to view logs live while saving them, use:

adb logcat -b crash | tee logfile.txt

These commands help focus our debugging efforts, isolating critical log messages, stack traces, or error messages from the noise.

Best Practices for Debugging with logcat

When examining Android logs, keep these key points in mind:

1. Timestamps:

• They indicate the sequence of events and help correlate logs with user actions or system events.

2. Log Levels:

• Pay attention to DEBUG, INFO, WARNING, and ERROR messages.
• Higher log levels like ERROR and WARNING often signal critical issues.

• Silence undesired log entries with the SILENT priority level.

3. Log Tags:

• Tags help filter messages by component or subsystem, enabling targeted troubleshooting.

4. Error Messages & Stack Traces:

• Look for keywords such as exception or error.
• Stack traces reveal the function call hierarchy leading up to the error, making it easier to pinpoint the source.

5. Log Message Sources

• A test build might include extra log messages coded in by developers.
• Make sure to make a clear distinction between logs generated by the system or source code.

• Extra Tip:

Use the adb logcat -v color command to view color-coded output:

6. Clear and Consistent Reporting:

• Always clear the log buffer after a test run using:

adb logcat -c

• This ensures new logs are not mixed with previous events, providing clarity in your reports.

By incorporating these practices, you ensure that your logcat output is not only comprehensive but also actionable for development teams.

Conclusion

Mastering ADB logcat goes beyond simply running a command — it involves understanding the nuances of buffer management, leveraging advanced filtering techniques, and using best practices to capture actionable insights. Whether you’re troubleshooting a crash on a disconnected device or preparing detailed bug reports with screenshots, videos, and logs, the right command-line tools and workflows are indispensable.

Embrace these advanced logcat techniques to elevate your debugging process, ensure your bug reports are robust, and help your development team quickly zero in on critical issues. For more tips and detailed command usage, keep exploring and refining your ADB toolkit.

𝓗𝒶𝓅𝓅𝓎 𝓉𝓮𝓈𝓉𝒾𝓃𝓰 𝒶𝓃𝒹 𝒹𝓮𝒷𝓊𝓰𝓰𝒾𝓃𝓰!

I welcome any comments and contributions to the subject. Connect with me on LinkedIn, X , GitHub, or Insta. Check out my website.

If you find this post useful, please consider buying me a coffee.