LogSleuth
v0.4.1Screenshots
(12)About Application
LogSleuth
A powerful logcat viewer and embedded logging SDK for Android. On a mission to be the easiest and most delightful logging tool on Android.
Screenshots
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). Shizuku, root, or one ADB grant unlocks the device log. Shizuku stays the recommended path when the phone is not rooted.
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
| Feature | Details |
|---|---|
| Live logcat | threadtime rows with level colors, pid·tid·uid columns and per-app icons |
| Buffer rail | The right edge draws the whole buffer as a severity fingerprint, with a draggable viewport thumb and a Line N of M readout |
| Smooth tail-follow | Conveyor-style auto-scroll that tracks the arrival rate; a fling up detaches, a fling back re-pins |
| Pause & buffer | Freeze the display while lines keep buffering underneath — the banner counts what's waiting, under the filter you are actually using |
| Search | Query across the whole buffer: hit counter, highlighted matches, prev/next jumps |
| Jump controls | FABs to snap to the oldest buffered line or back to the live tail |
| Engine chip | Streaming / Connecting / Stopped / Error at a glance — with the real cause (e.g. logcat exited 1) shown when it fails; auto-reconnects with backoff |
| Restart logging | Overflow action that reconnects a wedged stream, keeping the resume stamp so the ring buffer is not dumped again |
Narrow it down
| Feature | Details |
|---|---|
| Filters | Level threshold (V–A), tag, keyword, exclude-pattern, regex toggle — combinable |
| Filter presets | Save a filter combo, reapply it later; presets manage their own screen |
| Filter editor | Pick a package and an allowed level set; creating a filter from a log line opens the editor prefilled instead of saving a fixed rule |
| Per-app filter | Chip over the stream filters to one app (package names need the uid column, so Shizuku or root) |
| App picker | Installed-app list with icons and per-app line stats |
Act on what you see
| Feature | Details |
|---|---|
| Entry detail | Tap a row for the full message, pid/tid/uid, copy message or raw line |
| Multi-select | Long-press a row, tap to extend the range, copy the whole block |
| Clear / save by scope | Wipe or snapshot everything, or check the apps you want in a two-pane picker with per-app stats |
| Session snapshot | Save the current buffer as a session in one tap |
Record & replay
| Feature | Details |
|---|---|
| Background recording | Foreground service with a live line-count notification (Stop / Bookmark actions) |
| Quick Settings tile | "Record logs" tile shows the live count while active |
| Floating bubble | Optional overlay with record / bookmark / hide controls over other apps (needs the overlay permission) |
| Bookmarks | Timestamp "it happened NOW" during a recording — visible in the session's Bookmarks tab |
| Auto-stop limits | Configurable size cap (8–512 MB, default 64) and duration cap (0–24 h, default unlimited) |
| Pre-start backfill | A recording can include the lines buffered before you hit record |
| Session replay | Reopen any session — Logs / Crashes / Bookmarks tabs, same filters and search as the live stream |
| Manage sessions | Swipe-to-delete with Undo; every session can be shared again later |
Crash & ANR detection
| Feature | Details |
|---|---|
| Live detection | FATAL EXCEPTION, native Fatal signal and ANR signatures flagged while streaming or recording |
| In-app event list | Crashes grouped by app (icon, name, count). Search, sort, and open one app's stack, version, and the surrounding lines. Delete one app's crashes with Undo |
| Crash search | Search the stack and the saved surrounding logs, with previous/next, a hit counter, and the current match scrolled into view. Back closes the search before leaving the page |
| Ignore an app | Ignore or un-ignore the crashing package from the crash screen itself |
| Notifications | Save and notify are separate for Java crashes, native crashes, and ANRs. Each app can have its own channel, so muting one in system settings keeps the record. The alert shows the stack, copies it, and opens that crash |
| Surrounding logs | Up to 200 lines from the moment of the crash are stored beside it and included in the share zip |
Reports, export & import
| Feature | Details |
|---|---|
| Report wizard | Three steps: pick the misbehaving app → reproduce while LogSleuth records → share ZIP/TXT or keep it in Sessions. A crash in the target app is flagged automatically |
| Export | Sessions and the report share as .txt or .zip (the zip bundles device info). A crash shares as plain text, or as a file when the stack is too big for the share sheet |
| Import | Open .zip/.txt/.log from a file manager or share sheet — LogSleuth renders it as a session (this is also how SDK exports arrive) |
Quality-of-life
| Feature | Details |
|---|---|
| Guided tour | A 17-step hands-on tour that drives the real UI — replay it anytime from Settings → About |
| Setup wizard | Shizuku, an opt-in root card, and a copyable ADB grant, re-checkable in place |
| Bilingual | English & 简体中文, plus an in-app language override |
| Themes & text | System / Light / Dark themes; Compact / Default / Comfortable log text sizes |
| In-app updates | GitHub Releases check, release notes, resumable APK download (pause/resume/cancel), one-tap install, version history |
| Tunable buffer | On-screen ring buffer from 1,000 to 200,000 entries (default 20,000). Optional cold start that follows only new lines; a reconnect still continues from the last line |
| Log rows | Optional full lines instead of an 8-line clamp. Search has a match-case toggle on the search bar |
| Sessions | Rename any session from the list or its detail screen |
| Restore defaults | One button in Settings puts every preference back to its default — after a confirmation that says what is kept |
| Community | The QQ group and the Bilibili space are one tap away at the bottom of Settings |
| Background watch | Crash watch that keeps running off screen — with a specialUse foreground service, so it no longer trips the Android 15 time limit |
Embedded SDK (logsleuth-sdk)
For app developers — everything above, pointed at your app's process:
| Capability | Details |
|---|---|
| Zero requirements | No permissions, no network, no accounts — an app can always read its own logs |
| Capture | Own-process logcat thread, Java crash handler (chained to the previous one), main-thread ANR watchdog |
| Storage | Ring-buffered log files (default 3 × ≤2 MB), automatic rotation |
| Privacy | addRedaction(Regex) strips secrets from recorded logs |
| Callbacks | Sleuth.onCrash { … } — fires on next start by default, or immediately if you prefer |
| Sharing | Sleuth.shareLogs(activity) zips logs + device info + metadata and opens the system share sheet |
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. Any one of these grants is enough:
- 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.
- Root — if the phone already runs Magisk, KernelSU, or APatch, turn
root on in the setup wizard. LogSleuth does not exec
suuntil you ask, so an unrooted phone never sees a grant dialog. Root reads the same full log as Shizuku, including per-app filtering. Auto mode still prefers Shizuku when both are available; Settings can put root first. - ADB grant — with a PC, run once. The permission stays until you uninstall:
On Android 13 and later this grant is not a background log source. Android only shows the approval dialog while LogSleuth is on screen, and a start from the background is refused and remembered for about a minute. An already-approved stream keeps running after you leave. Shizuku and root are not affected, including the boot crash watch.adb shell pm grant io.github.shiaho777.logsleuth.app android.permission.READ_LOGS
The setup wizard walks you through these 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, pick only Warn and Error (or any level set) and a tag or keyword — or filter by app (Shizuku or root). 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:
| Option | Default | Meaning |
|---|---|---|
tagFilter(String) | null (all) | Record only lines whose tag contains it (plus all ERROR lines) |
maxFiles(Int) | 3 | Ring-buffer file count, 1–20 |
maxFileBytes(Long) | 2 MB | Rotate after this many bytes per file (min 64 KB) |
captureLogcat(Boolean) | true | Set false to record crashes/ANRs only |
watchAnr(Boolean) | true | Main-looper heartbeat ANR watchdog |
onCrashInvokedOnNextStart(Boolean) | true | Deliver the crash callback on next init instead of at crash time |
addRedaction(Regex) | — | Extra patterns stripped before writing to disk |
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 / root 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:
| Permission | Used for |
|---|---|
READ_LOGS | Device log when you use the ADB grant. On Android 13+ a new logcat starts only while LogSleuth is on screen. Shizuku and root read logs through a shell instead |
moe.shizuku…API_V23 | Talking to the Shizuku service |
FOREGROUND_SERVICE + …_SPECIAL_USE | Keeping the crash watch and background recording alive |
POST_NOTIFICATIONS | Recording status, crash/ANR alerts, auto-stop notices |
SYSTEM_ALERT_WINDOW | Floating record/bookmark bubble — only if you enable it |
RECEIVE_BOOT_COMPLETED | Restarting the crash watch after a reboot — only if you left it on |
INTERNET | Update checks against GitHub Releases only — no analytics, no ads |
REQUEST_INSTALL_PACKAGES | Installing downloaded APK updates |
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)
Documentation
The documentation site is published at shiaho777.github.io/LogSleuth:
| Section | URL | Covers |
|---|---|---|
| Guide | /guide/ | Getting started, log access, filters and rules, recording and crashes |
| 简体中文 | /zh/guide/ | The same guide in Chinese |
| Developer | /developer/ | Architecture, change recipes, the release runbook |
The site source lives in docs/; run it locally with
cd docs && npm install && npm run dev.
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.
Contact
| Platform | Link |
|---|---|
| GitHub | github.com/shiaho777/LogSleuth |
| Bilibili | space.bilibili.com/2127032909 |
| QQ Group | 1127256026 — tap to join |
License
Release Notes & Changelog
LogSleuth 0.4.1 — a steadier stream and a safer update path: reconnect-safe logcat, verified resumable downloads, and fixes across recording, search, redaction and timestamps.
versionName 0.4.1, versionCode 12.
Requires Android 8.0 (API 26)+.
This build is signed with the same key as 0.4.0, so it installs over 0.4.0 — your settings, sessions and crash history stay where they are.
Improved
- Update downloads are verified and resumable. The in-app updater checks the finished file against the release's advertised size, resumes from the bytes already on disk, throws away a stale partial file instead of appending to it, and says exactly why a transfer failed — HTTP status, incomplete file or stalled connection — in the app's language. (#159, closes #158; #177, closes #176)
- The SDK reconnects without duplicating the log. When the host app's
logcatdies, the SDK resumes from the last delivered line instead of writing the whole buffered ring to disk a second time. (#139, closes #138) - Recording keeps the whole active filter. pid, tid and uid — silently dropped when a recording started from the stream screen — now narrow the recording too, because the service receives the filter as one value instead of a hand-maintained set of extras. (#141, closes #140)
- Search stays responsive on a busy stream. Hit re-indexing runs at most once every 250 ms instead of up to 60 full scans a second, and the rail's severity fingerprint is computed on the composition thread so a buffer trim can no longer crash the screen. (#165, closes #164; #163, closes #162)
- Pause, filters, search, recording and reconnects are serialized. List state is read under the lock that owns it, superseded filter and search work is cancelled instead of landing late, recording start/stop and cap stops share one lifecycle lock, and the engine checks stream ownership under its own lock. (#143, closes #142; #145, closes #144; #147, closes #146; #149, closes #148)
- Rotating the screen no longer re-runs the launch action. A shared file is imported once, and notification deep links no longer stack the same screen again. (#161, closes #160)
Fixed
- Reconnects survive New Year and non-Gregorian locales. The resume stamp now carries a full
yyyy-MM-dddate built from a Gregorian calendar with US digits, so a stream that crosses midnight on 31 December resumes instead of asking for a date a year ahead; log timestamps no longer jump by 543 years on Buddhist-calendar devices. (#169, closes #168; #171, closes #170) - Saving or sharing a session reports failure instead of doing nothing. Stream snapshots, range selections, exports and shares now show a message when they fail. (#151, closes #150; #157, closes #156)
- Deleting a session no longer orphans its log file. If the file cannot be removed, the session stays and a message explains why, so the delete can be retried from the list. (#173, closes #172)
- Redaction masks the whole match and also applies to crash reports before they are stored. (#155, closes #154)
- Crash search matches the original text. Searching a character whose lowercase form is longer (
İ) no longer misplaces the highlight or crashes the screen. (#167, closes #166) - Live search hits follow their log line. When the ring buffer evicts older rows, next/previous now jumps to the line that actually matched instead of a shifted position. (#179, closes #178)
- Zip imports read the whole header, so a shared bundle is no longer misclassified from a short first read. (#153, closes #152)
- The README permission table matches the manifest, including the restart-after-reboot permission and the
specialUseforeground service. (#137, closes #136)
LogSleuth 0.4.1 —— 更稳的日志流、更安全的更新:断线重连不再重复写日志,下载可校验可续传,录制、搜索、脱敏和时间戳一并修好。
versionName 0.4.1,versionCode 12。
需要 Android 8.0(API 26)及以上。
这一版和 0.4.0 用的是同一把签名密钥,可以直接覆盖安装——设置、会话和崩溃记录都还在。
改进
- 更新下载会校验,也能续传。 应用内更新器会核对完成文件与发行页公布的大小,从磁盘上已有的字节继续下载,丢弃过期的不完整文件而不是继续追加,并用应用当前语言说明失败原因——HTTP 状态码、文件不完整或连接停滞。(#159, closes #158; #177, closes #176)
- SDK 重连不再重复写日志。 宿主应用的
logcat死掉后,SDK 从最后一条已交付的日志继续,而不是把整个缓冲区再写一遍到磁盘。(#139, closes #138) - 录制会带上完整的当前过滤器。 从日志流页面开始录制时,pid、tid 和 uid 以前会被悄悄丢掉;现在服务收到的是一整个过滤器值,而不是一份需要手工维护的 extra,录制范围会和屏幕上看到的一致。(#141, closes #140)
- 日志很多时搜索也不会把界面拖住。 命中重建最多每 250 毫秒跑一次,而不是每秒最多 60 次全量扫描;右侧轨道的级别指纹改在组合线程计算,缓冲区淘汰旧行时不会再让页面崩溃。(#165, closes #164; #163, closes #162)
- 暂停、过滤、搜索、录制和重连都串行化了。 列表状态在拥有它的锁内读取,过期的过滤和搜索任务会被取消而不是晚到覆盖,录制的开始、停止和容量上限停止共用一把生命周期锁,引擎也在自己的锁内检查日志流的归属。(#143, closes #142; #145, closes #144; #147, closes #146; #149, closes #148)
- 旋转屏幕不再重复执行启动动作。 分享进来的文件只会导入一次,通知深链也不会把同一个页面重复压进返回栈。(#161, closes #160)
修复
- 跨年和非公历地区也能正常重连。 续读时间戳现在带完整的
yyyy-MM-dd日期,由公历和 US 数字生成,所以 12 月 31 日午夜断开的流会正常续读,而不是去请求一年后的日期;在佛历设备上,日志时间也不会再偏移 543 年。(#169, closes #168; #171, closes #170) - 保存或分享会话失败时会提示,而不是毫无反应。 日志流快照、范围选择、导出和分享失败时都会弹出提示。(#151, closes #150; #157, closes #156)
- 删除会话不会再留下孤儿日志文件。 如果文件删不掉,会话会保留并说明原因,可以回到列表重试。(#173, closes #172)
- 脱敏会遮住整个命中片段,并且在崩溃报告写入存储前也会执行。(#155, closes #154)
- 崩溃搜索按原始文本匹配。 搜索小写形式更长的字符(如
İ)时,高亮不会错位,页面也不会崩溃。(#167, closes #166) - 实时搜索命中跟着日志行走。 环形缓冲淘汰旧行时,上一条/下一条会跳到真正命中的那一行,而不是错位后的位置。(#179, closes #178)
- Zip 导入会读取完整文件头,分享的压缩包不会再因为第一次读取太短而被误判。(#153, closes #152)
- README 的权限表与清单文件一致,补上了开机重启权限和
specialUse前台服务。(#137, closes #136)
Declared Android Permissions
10 totalShizuku API Permissions
This application connects to the Shizuku service to execute system-level operations with ADB elevated privileges.
Standard Android Permissions
Specifications
Install via ShizuStore to enable automatic updates and silent installations using Shizuku.
More in Development utilities
Other applications in this category
LibChecker
LibChecker
An app to view libraries used in apps on your device. Uses Shizuku to determine the installation source of other apps.














