Native rooted Android app for block-I/O tracing

[1a1a11a]

Summary

Adds a native Android app (app/ module) that runs the block-I/O collector on-device with a Jetpack Compose Start/Stop UI and a foreground service, instead of driving the Python CLI over adb. It emits the same CSV schema as the Python tracer and the Linux tracer — only the compression container differs (.csv.gz vs .csv.zst).

This builds on the Python CLI already in the repo (which remains the reference collector and host driver).

How it works

MainActivity (Compose UI)  ──►  TracerService (foreground)  ──►  TraceEngine
                                                                   ├─ RootShell ......... su exec + streaming
                                                                   ├─ FtraceControl ..... enable/stream/teardown tracefs
                                                                   ├─ FtraceParser ...... port of parsers.py
                                                                   ├─ BlockPairer ....... issue→complete latency
                                                                   ├─ Proc/SystemSnapper
                                                                   └─ TraceWriter ....... gzip CSV + manifest.json

• Block I/O: the service opens a root (su) shell that sets trace_clock=mono, enables block/block_rq_issue + block/block_rq_complete, and streams trace_pipe. Kotlin pairs issue→complete by (device, sector) to recover device latency + a monotonic request_id, and restores ftrace state on stop.
• Snapshots: periodic ps -A (process) + getprop//proc (system spec).
• Output: gzip CSV streams + manifest.json (anonymized machine id, CLOCK_MONOTONIC→REALTIME offset, row counts) under Android/data/com.cachemon.iotracer/files/traces/<session>/.
• Falls back to snapshot-only when root/block tracepoints aren't available.

Schema parity

Schema.kt, FtraceParser.kt, and BlockPairer.kt are 1:1 ports of schema.py / parsers.py (same SCHEMA_VERSION = 3, same column order) and must be kept in sync — noted in docs/ANDROID_APP.md.

Testing

• JVM unit tests (app/src/test) mirror tests/test_parsers.py: common-header parsing, rwbs decoding, issue/complete pairing + latency, reused-sector disambiguation, unmatched completions. Verified locally — compiled the pure-Kotlin engine with Kotlin 1.9.24 and ran the tests: 8 passed.
• CI (.github/workflows/android.yml) runs :app:testDebugUnitTest and assembles the debug APK on every push/PR, uploading the APK as an artifact. (The full Android build needs the Android SDK, which isn't in the dev sandbox — CI is the build gate.)

Build & run

gradle :app:assembleDebug          # or open in Android Studio
adb install app-debug.apk          # rooted/userdebug device
# Launch "IO Tracer", grant su, Start → reproduce workload → Stop
adb pull /sdcard/Android/data/com.cachemon.iotracer/files/traces ./traces

Notes

• Requires root for block tracing (reads /sys/kernel/tracing via su); minSdk 26.
• No Gradle wrapper jar is committed — Android Studio generates it, and CI uses a pinned system Gradle 8.7. (Happy to commit the wrapper if you'd prefer.)

Files

• app/ — Gradle module, manifest, Kotlin engine + service + Compose UI, unit tests
• build.gradle.kts, settings.gradle.kts, gradle.properties
• .github/workflows/android.yml
• docs/ANDROID_APP.md; README pointer

🤖 Generated with Claude Code

https://claude.ai/code/session_01VbHpkJ1MdVfGz9bi6Ekb1i

---

Generated by Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[gemini-code-assist]

Code Review

This pull request introduces a native Android application for rooted block-I/O tracing, featuring a Compose-based UI, a foreground service, ftrace streaming and parsing, and periodic system/process snapshots. The review feedback highlights several critical improvements for thread safety, performance, and code quality. Specifically, it suggests using MutableStateFlow.update to ensure atomic state updates, reusing SimpleDateFormat via ThreadLocal and removing redundant body.trim() allocations to reduce garbage collection pressure in high-frequency tracing paths, buffering GZIPOutputStream to optimize disk writes, and replacing the unidiomatic use of Any with nullable types in BlockPairer for better type safety.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Add the kotlinx.coroutines.flow.update import to support atomic updates on MutableStateFlow.

Suggested change

	import kotlinx.coroutines.flow.MutableStateFlow
	import kotlinx.coroutines.flow.StateFlow
	import kotlinx.coroutines.flow.asStateFlow
	import kotlinx.coroutines.flow.MutableStateFlow
	import kotlinx.coroutines.flow.StateFlow
	import kotlinx.coroutines.flow.asStateFlow
	import kotlinx.coroutines.flow.update

[gemini-code-assist]

The custom update function is not thread-safe or atomic. Since TracerState.update is called concurrently from multiple background threads (e.g., readerThread, snapshotThread, and the main thread), concurrent updates can overwrite each other, leading to lost updates in UI counters. Use the built-in, atomic MutableStateFlow.update extension function instead.

Suggested change

	object TracerState {
	private val _status = MutableStateFlow(TraceStatus())
	val status: StateFlow<TraceStatus> = _status.asStateFlow()
	fun update(transform: (TraceStatus) -> TraceStatus) {
	_status.value = transform(_status.value)
	}
	fun reset() {
	_status.value = TraceStatus(rootAvailable = _status.value.rootAvailable)
	}
	}
	object TracerState {
	private val _status = MutableStateFlow(TraceStatus())
	val status: StateFlow<TraceStatus> = _status.asStateFlow()
	fun update(transform: (TraceStatus) -> TraceStatus) {
	_status.update(transform)
	}
	fun reset() {
	_status.update { TraceStatus(rootAvailable = it.rootAvailable) }
	}
	}

[gemini-code-assist]

Creating a new SimpleDateFormat and Date instance on every single block I/O completion event (which can happen thousands of times per second) introduces significant garbage collection pressure and CPU overhead on Android. Reuse a single SimpleDateFormat instance wrapped in a ThreadLocal to ensure thread safety while avoiding repeated allocations.

    private fun monoToWall(monoNs: Long): String {
        val realNs = monoNs + realOffset
        return wallFormat.get().format(java.util.Date(realNs / 1_000_000L)) + "000"
    }

[gemini-code-assist]

Add a thread-local SimpleDateFormat instance to the companion object to be reused by monoToWall.

    companion object {
        fun checkRoot(): Boolean = RootShell().available()

        private val wallFormat = ThreadLocal.withInitial {
            java.text.SimpleDateFormat("yyyy-MM-dd HH:mm:ss.SSS", java.util.Locale.US)
        }
    }

[gemini-code-assist]

Calling body.trim() allocates a new string on every single ftrace line parsed. Since the LINE regex in parseCommon already strips leading spaces before the body group, and trailing spaces do not affect the matching behavior of find(), body.trim() is redundant and can be safely removed to avoid unnecessary allocations.

Suggested change

	fun parseIssue(body: String): Issue? {
	val m = ISSUE.find(body.trim()) ?: return null
	val (dev, rwbs, bytes, sector, nsect) = m.destructured
	return Issue(devToMajMin(dev), rwbs, bytes.toLong(), sector.toLong(), nsect.toLong())
	}
	fun parseComplete(body: String): Complete? {
	val m = COMPLETE.find(body.trim()) ?: return null
	val (dev, rwbs, sector, nsect, err) = m.destructured
	return Complete(devToMajMin(dev), rwbs, sector.toLong(), nsect.toLong(), err.toInt())
	}
	fun parseIssue(body: String): Issue? {
	val m = ISSUE.find(body) ?: return null
	val (dev, rwbs, bytes, sector, nsect) = m.destructured
	return Issue(devToMajMin(dev), rwbs, bytes.toLong(), sector.toLong(), nsect.toLong())
	}
	fun parseComplete(body: String): Complete? {
	val m = COMPLETE.find(body) ?: return null
	val (dev, rwbs, sector, nsect, err) = m.destructured
	return Complete(devToMajMin(dev), rwbs, sector.toLong(), nsect.toLong(), err.toInt())
	}

[gemini-code-assist]

Using Any to represent union types like Int | String or Double | String is highly unidiomatic in Kotlin and bypasses compile-time type safety. Use standard nullable types (Int?, Double?, Long?) instead. Since Csv.field already maps null to "", this change is fully compatible and much cleaner.

Suggested change

	data class DsRow(
	val operation: String,
	val pid: Any, // Int, or "" when the issue was not seen
	val tid: String,
	val command: String,
	val sector: Long,
	val size: Long,
	val latencyMs: Any, // Double, or "" when unknown
	val device: String,
	val flags: String,
	val cpuId: Int,
	val ppid: String,
	val queueLatencyMs: String,
	val commandFlags: String,
	val operationCode: String,
	val requestId: Any, // Long, or "" when the issue was not seen
	val monoNs: Long,
	)
	data class DsRow(
	val operation: String,
	val pid: Int?, // null when the issue was not seen
	val tid: String,
	val command: String,
	val sector: Long,
	val size: Long,
	val latencyMs: Double?, // null when unknown
	val device: String,
	val flags: String,
	val cpuId: Int,
	val ppid: String,
	val queueLatencyMs: String,
	val commandFlags: String,
	val operationCode: String,
	val requestId: Long?, // null when the issue was not seen
	val monoNs: Long,
	)

[gemini-code-assist]

Update the fallback completion row instantiation to use idiomatic null values instead of empty strings.

        } else {
            // Completion with no recorded issue (started before tracing began).
            DsRow(
                operation = operation,
                pid = null,
                tid = "",
                command = c.comm.take(16),
                sector = info.sector,
                size = info.nsect * 512,
                latencyMs = null,
                device = info.device,
                flags = flags,
                cpuId = c.cpu,
                ppid = "",
                queueLatencyMs = "",
                commandFlags = "",
                operationCode = "",
                requestId = null,
                monoNs = c.monoNs,
            )
        }

[gemini-code-assist]

GZIPOutputStream is not internally buffered when writing to the underlying FileOutputStream. Wrapping the FileOutputStream in a BufferedOutputStream (via .buffered()) before passing it to GZIPOutputStream significantly reduces the number of disk write system calls and improves write performance.

Suggested change

	GZIPOutputStream(FileOutputStream(file)).bufferedWriter(Charsets.UTF_8).use { w ->
	GZIPOutputStream(FileOutputStream(file).buffered()).bufferedWriter(Charsets.UTF_8).use { w ->