Extracting Logs With Logcat

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.