LogSleuth

A powerful, root-free logcat viewer & embedded logging SDK for Android. On a mission to be the easiest and most delightful logging tool on Android.

简体中文

Screenshots

Live logcat stream	Search & hit jumps	Filters & presets
Crash & ANR detection	Log entry detail	Multi-select & copy
Per-app scope picker	Recording sessions	Session replay
Guided report & export	Save & share	Setup & grants
Settings & in-app updates	Guided tour	Embedded SDK sample

What is LogSleuth?

LogSleuth is an open-source (Apache-2.0) Android logging toolkit with two halves that work together:

• The viewer app — a polished, Logcat-style live reader for the whole device, written in Kotlin + Jetpack Compose (Material 3). No root: one grant via Shizuku or ADB unlocks everything.
• logsleuth-sdk — a drop-in library for your own app that records its logs, crashes and ANRs with zero permissions and zero network, then packages them into a zip your users can send you. LogSleuth the viewer opens those zips directly.

Feature overview

Watch the stream

Narrow it down

Act on what you see

Record & replay

Crash & ANR detection

Reports, export & import

Quality-of-life

Embedded SDK (logsleuth-sdk)

For app developers — everything above, pointed at your app's process:

Getting started

1. Install

Grab the APK from Releases and install it (Android 8.0+ / API 26, ~2.4 MB).

2. Grant log access

Since Android 4.1, apps cannot read other apps' logs — a platform rule that applies to every logcat app. One of these two one-time grants is required:

1. Shizuku (recommended) — no root, no PC needed on Android 11+ via Wireless Debugging. Install Shizuku, start it once, and authorize LogSleuth. This also unlocks per-app filtering.
2. ADB one-time grant — with a PC, run once (persists until uninstall):

   adb shell pm grant io.github.shiaho777.logsleuth.app android.permission.READ_LOGS
   

The setup wizard walks you through either path on first launch and can be reopened any time from Settings → Log access → "Open setup guide".

3. Take the tour

On first run a 17-step coach-mark tour drives the real UI — it opens the filter bar, pauses the stream, types a search query, and pops the scope picker for you. Skip it or replay it later from Settings → About → "Replay guided tour".

Everyday workflows

• "The app keeps crashing for a user" → Report tab → pick the app → start recording → hand them the phone → Stop & share. Crashes inside the window are flagged and attached automatically.
• "It's too noisy" → unfold the filter bar, set level ≥ Warn and a tag or keyword — or filter by app (Shizuku). Save the combo as a preset.
• "I need to mark when it happened" → enable Floating controls (needs the overlay permission) or use the Quick Settings tile: record + bookmark without leaving the app under test.
• "I got a log zip / txt" → open it with LogSleuth or use Import on the Sessions tab — it lands as a replayable session.
• "That line matters" → tap its ℹ icon for the full message and copy buttons; long-press to multi-select and copy a whole block.

Embedding the SDK

Add the module to your project (source module today; a Maven artifact is planned after the public release):

// app/build.gradle.kts
implementation(project(":sdk"))

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        Sleuth.init(this)   // capture starts immediately — no permissions
    }
}

// Anywhere in your app — e.g. a "send logs" support button:
Sleuth.shareLogs(activity)   // opens the system share sheet with a zip

Configuration via SleuthConfig.Builder:

Full API:

Sleuth.init(context, SleuthConfig.Builder().tagFilter("net").build())
Sleuth.onCrash { report -> /* queue it — runs on next start by default */ }
Sleuth.log("Checkout", "order=42 placed")       // injected into the stream
Sleuth.logException("Checkout", throwable)
val files: List<File> = Sleuth.logFiles()       // raw ring-buffer files
Sleuth.shareLogs(activity)

The zip contains device.txt (manufacturer/model/Android version), meta.txt and the log files — and LogSleuth the viewer opens it natively, so your support flow is "send me the zip" → they open it → you replay it.

Architecture

LogcatSource (local READ_LOGS / Shizuku shell)
  → LogcatEngine (single owner of the logcat process, auto-reconnect)
      ├→ Stream UI (level colors, filters, search, pause/buffering)
      ├→ RecordingManager (foreground service → session files + Room)
      └→ CrashDetector (FATAL EXCEPTION / Fatal signal / ANR → events + notifications)

logsleuth-sdk (embedded in a host app — zero permissions, zero network):
  Sleuth.init → own-process logcat capture + crash handler + ANR watchdog
              → ring-buffered log files (with secret redaction)
              → one-tap zip share (opens in the viewer for replay)

Permissions

Everything the app asks for, and why:

The SDK itself declares no permissions at all — it only ever reads its host app's own logs.

Project structure

app/      The LogSleuth viewer app (Kotlin + Jetpack Compose, Material 3)
sdk/      logsleuth-sdk — the embeddable, zero-permission logging library
sample/   Demo app showing SDK integration

Build from source

Requires JDK 17+ and Android SDK platform 36.

git clone https://github.com/shiaho777/LogSleuth.git
cd LogSleuth
./gradlew assembleDebug          # app + sdk + sample
./gradlew test                   # unit tests
python3 scripts/check_string_parity.py   # bilingual string gate (runs in CI)

Download

• GitHub Releases (see Releases page)
• F-Droid (planned after first public release)
• Google Play (planned)

Contributing

See CONTRIBUTING.md. Bug reports and feature requests are welcome via GitHub Issues.

License

Apache-2.0

LogSleuth 0.3.3 — hotfix for the Shizuku access path.

Fixed

• Shizuku stream failed instantly with read failed: EBADF — the RemoteProcess wrapper mapped the AIDL streams swapped, so the reader got the write-only end of the remote stdin pipe and the first read blew up. The mapping now matches the official ShizukuRemoteProcess. Verified end-to-end against a live Shizuku service: v0.3.2 reproduces the EBADF; this build streams the full device logcat as the shell user. (#97)

Assets

Signed with the LogSleuth release key (v2+v3). Requires Android 8.0 (API 26)+.