extracting-logs-with-logcat

Extracting Logs With logcat — Reading Device Logs

This skill covers adb logcat end-to-end: streaming vs dumping, buffer selection, filter expressions, format flags, PID and time filters, file rotation, and the R8 rule that strips Log.d from release builds. The companion CI capture-on-failure pattern lives in ../../automation/scripting-adb-for-ci/SKILL.md.

When to use this skill

• A test fails on CI; the developer needs to dump the device log into the artefact archive.
• The developer's adb logcat | grep MyApp is overwhelming the SSH session — the logcat-side filter is the fix.
• A scenario only reproduces inside system_server or crash buffers, not the default main.
• The developer wants structured logs (-v json) for machine ingestion.
• A Log.d("Sensitive", "...") call appears to leak in release — the R8 -assumenosideeffects rule is missing.
• Logs disappear after the app is killed by Doze/ANR — --pid plus a re-resolution loop is needed.

When NOT to use this skill

• Capturing a screenshot or video. Use ../../capture/capturing-screenshots-and-screenrecord/SKILL.md.
• Pulling a generic file from the device. Use ../../transfer/extracting-test-artifacts/SKILL.md.
• The whole script — retries, port forwarding, parallel device fan-out. Use ../../automation/scripting-adb-for-ci/SKILL.md.
• Driving gestures or settings changes. Use ../../control/injecting-input-and-state/SKILL.md.

Prerequisites

• adb get-state returns device. See ../../devices/connecting-to-devices/SKILL.md.
• For -v json: device API 30+ (Android 11+). Stack with -v UTC -v year for unambiguous timestamps.
• For per-PID filtering: adb shell pidof -s <pkg> requires API 24+ (toybox pidof -s); on older releases use adb shell ps -A | grep <pkg>.

Three fundamental operations

(Verbatim quotes from developer.android.com/tools/logcat.)

Idiomatic CI capture pattern:

adb logcat -c                           # clear before scenario
./run-scenario.sh                       # reproduce
adb logcat -d > artifacts/log.txt       # dump after

Buffer selection

-b <name> selects which kernel/userspace ring buffer is read. Buffers (developer.android.com/tools/logcat):

Multiple -b flags or comma-separated lists both work:

adb logcat -b radio
adb logcat -b main -b radio -b events
adb logcat -b main,radio,events

The events buffer is where to look for am_*, wm_*, input_focus, notification_* — emitted by the framework for instrumentation, not for human reading. Decode tag names with:

adb logcat -b events -v descriptive

Priority ladder + filter expressions

Filter specs are space-separated tag:priority pairs. * matches every tag.

Setting *:S silences everything, then any preceding tag:P re-enables that tag at priority P or above. The canonical "show only my app's logs" idiom:

adb logcat ActivityManager:I MyApp:D *:S

"Suppress all logs except ActivityManager (Info+) and MyApp (Debug+)" — developer.android.com/tools/logcat.

Other staples:

adb logcat *:W                          # warnings and above, all tags
adb logcat *:E                          # errors and above (very common in CI)

zsh/bash will glob-expand *:S outside of quotes when there is a file named S in cwd — quote when scripting:

adb logcat "ActivityManager:I MyApp:D *:S"

The same filter can be the host default via env var:

export ANDROID_LOG_TAGS="ActivityManager:I MyApp:D *:S"

Format flags — -v <format>

Format modifiers stack with -v (comma-combinable or repeatable):

adb logcat -v json -v UTC -v year       # Android 11+; structured stream, unambiguous time
adb logcat -b all -v color -d           # color dump, all buffers

Default-line example (developer.android.com/tools/logcat):

I/ActivityManager(  585): Starting activity: Intent { action=android.intent.action.MAIN ... }

Schema for brief: <priority>/<tag>(<PID>): <message>. threadtime adds date/time/TID.

Time and PID filters

• -T '<date> <time>' — start at the first entry on or after the given timestamp. Format matches threadtime, e.g. '01-01 12:00:00.000'.
• -T <count> — print the last N entries from the buffer, then continue streaming.
• -t <count> — print the last N entries, then exit (i.e. -t is -T with auto-quit).
• --pid <pid> — emit only entries from a single process. Combine with pidof:

adb logcat --pid=$(adb shell pidof -s com.example.app)

pidof -s returns a single pid; without -s you get a space-separated list which --pid will not accept directly. Wrap a re-resolution loop if the app may be killed and restarted (Doze, ANR, crash):

while true; do
  PID=$(adb shell pidof -s com.example.app 2>/dev/null)
  [ -n "$PID" ] && adb logcat --pid="$PID"
  sleep 1
done

Buffer rotation and persistence

For long captures, persist to a file with rotation:

adb logcat -G 16M                                     # grow the main buffer
adb logcat -g                                         # inspect sizes
adb logcat -b main -f /data/local/tmp/app.log \
           -r 1024 -n 8                               # 8x ~1MB rotated files (device-side)
adb shell logcat -b main -f /data/local/tmp/app.log \
           -r 1024 -n 8                               # same, but the device runs it

The -G resize is global to that buffer and persists across logd restarts (until reboot). Don't set 16 MB on a memory-constrained device and forget — release memory back with -G 256K after the suite if your CI farm is shared.

Stripping Log.d in release — R8 rule

android.util.Log calls remain in release APKs unless code-shrinking removes them. The standard idiom in proguard-rules.pro (R8/ProGuard):

-assumenosideeffects class android.util.Log {
    public static *** v(...);
    public static *** d(...);
    public static *** i(...);
    public static boolean isLoggable(java.lang.String, int);
}

-assumenosideeffects lets R8 treat the listed methods as pure no-ops, so all calls (and their string-builder argument expressions, when constants) are eliminated. Keep w, e, wtf for production diagnostics. With Timber: strip the BuildConfig.DEBUG-gated DebugTree plant and rely on a ReleaseTree that forwards to Crashlytics for warnings/errors.

For Compose specifically, do not -assumenosideeffects kotlin.jvm.internal.Intrinsics — it removes null-checks the compiler relies on.

Patterns

Pattern: WRONG — adb logcat | grep MyApp for filtering

# WRONG
adb logcat | grep MyApp
# WRONG because: the device sends every log line over the USB/TCP transport, then the host
# discards 99% via grep. On a busy device this saturates the transport and the grep can lag
# behind real time. Worse, `grep` runs without -F, so a tag that contains regex metacharacters
# (`.`, `(`, `+`) silently mismatches.

# RIGHT — filter at the logcat level
adb logcat MyApp:D *:S

The device only emits matching lines; the transport is uncongested.

Pattern: WRONG — assuming -T <count> exits

# WRONG
adb logcat -T 100 > tail.txt
# Hangs forever — -T <count> prints the last 100 lines THEN CONTINUES STREAMING.

# RIGHT — `-t` is `-T` with auto-exit
adb logcat -t 100 > tail.txt

Pattern: structured logs for machine ingestion

adb logcat -v json -v UTC -v year -d -b all > run.jsonl

Each line is a single JSON object — pipe through jq:

jq -c 'select(.priority == "ERROR")' run.jsonl

(-v json requires Android 11+ on the device.)

Pattern: capture-on-failure — clear, run, dump

adb logcat -c
./run-scenario.sh
RC=$?
if [ "$RC" -ne 0 ]; then
  adb logcat -d -v threadtime               > artifacts/logcat.txt
  adb logcat -d -b crash    -v threadtime   > artifacts/crash.txt
  adb logcat -d -b events   -v descriptive  > artifacts/events.txt
fi
exit "$RC"

-c clears before the run so the dump captures only the scenario's logs.

Pattern: PID-bound stream that survives a process restart

while true; do
  PID=$(adb shell pidof -s com.example.app 2>/dev/null)
  if [ -n "$PID" ]; then
    adb logcat --pid="$PID" -v threadtime
  fi
  sleep 1
done

The outer loop re-resolves the PID after Doze/ANR/crash kills and restarts the app.

Pattern: -f host vs device side

# host-side rotation (file lives on the developer machine)
adb logcat -b main -f ~/logs/app.log -r 1024 -n 8

# device-side rotation (file lives in /data/local/tmp on the device)
adb shell logcat -b main -f /data/local/tmp/app.log -r 1024 -n 8
adb pull /data/local/tmp/app.log ~/logs/app.log     # later

Mandatory rules

• MUST filter at the logcat level (e.g. MyApp:D *:S), not via host-side grep. Filtering on the device avoids saturating the transport.
• MUST quote filter strings containing * in zsh/bash (e.g. "MyApp:D *:S") — globbing eats the asterisk if a file named S exists in cwd.
• MUST use -t <count> for "tail and exit". -T <count> continues streaming after the initial dump.
• MUST use -d for snapshot dumps in CI. Streaming adb logcat requires explicit termination.
• MUST call adb logcat -c before reproducing a bug whose log dump you want to attach. Otherwise the dump includes irrelevant prior history.
• MUST distinguish adb logcat -f <file> (host-side path) from adb shell logcat -f <file> (device-side path). The shell forms diverge.
• MUST add the R8 -assumenosideeffects rule for android.util.Log v/d/i (and isLoggable) when shipping release APKs that previously called Log.d with sensitive data. Keep w/e/wtf.
• MUST NOT -assumenosideeffects kotlin.jvm.internal.Intrinsics — that removes null-check semantics the Kotlin compiler relies on.
• MUST NOT rely on -v json on devices below Android 11 — silently emits an empty stream.
• PREFERRED: stack -v threadtime,year,UTC (or -v threadtime -v year -v UTC) for unambiguous absolute timestamps in CI artefacts.
• PREFERRED: run with -G 16M for the main buffer when capturing slow-burning bugs, and reset to default in teardown.

Verification

• No script in scripts/ or .github/workflows/ pipes adb logcat directly into grep for filtering. All filters are passed as logcat args.
• CI capture-on-failure dumps include at least main, crash, and events buffers.
• Release APKs do not emit Log.d calls (verify via apkanalyzer dex packages app-release.apk | grep 'android.util.Log' returning only e/w/wtf).
• Filter strings containing *:S in shell scripts are quoted.
• All --pid invocations use pidof -s <pkg> (singular) and re-resolve in a loop if the app may restart.
• Every long-running adb logcat session in CI has a wall-clock budget (timeout 600s adb logcat ...) so a stuck session doesn't fill the disk.

References

• developer.android.com/tools/logcat — buffer table, priority ladder, filter expressions, -v threadtime/json/descriptive, format modifiers, -T/-t/--pid/-r/-n/-G/-g flags, line-format schema.
• developer.android.com/tools/adb — adb logcat host-side shorthand vs adb shell logcat.
• developer.android.com/studio/build/shrink-code — R8 -assumenosideeffects and the android.util.Log strip rule.
• developer.android.com/reference/android/util/Log — Log.v/d/i/w/e/wtf/isLoggable signatures.
• Research note tasks/research/A3-adb-observability-automation.md — full logcat surface, -f host-vs-device subtlety, R8 keep-rule rationale, capture-on-failure CI pattern.
• Sibling skill: ../../architecture/understanding-adb-architecture/SKILL.md — server / daemon, transport.
• Sibling skill: ../../devices/connecting-to-devices/SKILL.md — device states, wait-for-device.
• Sibling skill: ../../devices/connecting-over-wifi/SKILL.md — adb pair / adb connect.
• Sibling skill: ../../apps/installing-and-managing-apps/SKILL.md — installing the APK whose logs are being captured.
• Sibling skill: ../../tests/running-instrumented-tests-via-adb/SKILL.md — am instrument -w -r interplay with logcat.
• Sibling skill: ../../control/injecting-input-and-state/SKILL.md — driving gestures whose effects show up in logcat.
• Sibling skill: ../../capture/capturing-screenshots-and-screenrecord/SKILL.md — companion screenshot capture.
• Sibling skill: ../../transfer/extracting-test-artifacts/SKILL.md — pulling rotated log files from the device.
• Sibling skill: ../../automation/scripting-adb-for-ci/SKILL.md — full CI capture-on-failure / retry / cleanup patterns.
• Cross-set: ../../../instrumentation/runner/running-instrumented-tests-with-androidjunit4/SKILL.md — instrumentation logs interleaved with logcat.
• Cross-set: ../../../instrumentation/scenarios/launching-activities-with-activityscenario/SKILL.md — Activity lifecycle events surfaced in events buffer.
• Cross-set: ../../../fundamentals/strategies/applying-testing-strategies/SKILL.md — when log capture is the appropriate observability layer.