[feat] add a new toolbar button to clear logcat/timber/newtork/custom logs (#242)

## Summary by CodeRabbit

* **New Features**
  * Added a "Clear logs" toolbar button in the debug panel to wipe accumulated Logcat, Timber, and network entries mid-session; underlying sources now support opt-in clearing and accessibility text was added for the control.

* **Documentation**
  * CHANGELOG and README updated to document the new clear-logs capability.

* **Tests**
  * Added unit and integration tests verifying clear behavior and subsequent log/request collection.

Author: Manabu-GT

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Change Log
 
+## Version 2.5.0 *(2026-05-12)*
+
+### New Features
+
+* **Clear logs from the debug panel** – New `ClearAll` toolbar button wipes accumulated Logcat / Timber / network entries mid-session so the next bug report covers only the relevant repro window. Built-in sources implement the new public `Clearable` interface; custom `LogSource` / `NetworkRequestSource` implementations can opt in by also implementing `Clearable`. Resolves [#236](https://github.com/Manabu-GT/DebugOverlay-Android/issues/236).
+
 ## Version 2.4.0 *(2026-05-07)*
 
 ### New Features

README.md

@@ -56,6 +56,7 @@ Tap the overlay to open a full-screen diagnostic panel:
 - **UI** – View hierarchy via [Radiography](https://github.com/square/radiography)
 - **Device** – Hardware specs, OS info, battery, network status
 - **Bug Report** – One-tap HTML report with screenshot and diagnostics
+- **Clear Logs** – Toolbar button to wipe Logcat/Timber/network entries so the next bug report covers only the repro window
 
 <img src="art/readme_debug_panel.gif" alt="Debug Panel">
 

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/Clearable.kt

@@ -0,0 +1,30 @@
+package com.ms.square.debugoverlay
+
+import androidx.annotation.AnyThread
+
+/**
+ * Optional capability interface for data sources that can clear their
+ * accumulated entries. Used by the debug panel's "Clear logs" action so a
+ * subsequent bug report contains only entries from the relevant repro window.
+ *
+ * Any source registered with DebugOverlay (e.g. a [LogSource] or
+ * [NetworkRequestSource]) can opt in by additionally implementing this
+ * interface:
+ *
+ * ```kotlin
+ * class MyLogSource : LogSource, Clearable {
+ *   override fun clear() { /* reset internal buffer */ }
+ * }
+ * ```
+ *
+ * Behavior contract: after [clear] returns, subsequent emissions on the
+ * source's exposed flow MUST NOT include entries that were present before
+ * the call. Implementations may achieve this by resetting an in-memory
+ * buffer or by other means.
+ *
+ * Thread-safety: [clear] MUST be safe to call from any thread.
+ */
+public interface Clearable {
+  @AnyThread
+  public fun clear()
+}

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/data/DebugOverlayDataRepository.kt

@@ -2,6 +2,7 @@ package com.ms.square.debugoverlay.internal.data
 
 import android.app.Activity
 import android.content.Context
+import com.ms.square.debugoverlay.Clearable
 import com.ms.square.debugoverlay.LogSource
 import com.ms.square.debugoverlay.NetworkRequestSource
 import com.ms.square.debugoverlay.NoOpNetworkRequestSource
@@ -126,4 +127,16 @@ internal class DebugOverlayDataRepository(context: Context, scope: CoroutineScop
   fun stopJankStatsTracking(activity: Activity) {
     jankStatsDataSource.stopTracking(activity)
   }
+
+  /**
+   * Clears accumulated entries from sources that opt into [Clearable]:
+   * built-in logcat capture plus the current network and custom log sources
+   * when they implement [Clearable]. Custom external sources that don't
+   * implement [Clearable] are silently skipped.
+   */
+  fun clearAllLogs() {
+    logcatDataSource.clear()
+    (currentNetworkRequestSource.value as? Clearable)?.clear()
+    (customLogSource.value as? Clearable)?.clear()
+  }
 }

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/data/EvictingQueue.kt

@@ -56,4 +56,12 @@ public class EvictingQueue<T>(private val capacity: Int) {
    */
   @Synchronized
   public fun toList(): List<T> = queue.toList()
+
+  /**
+   * Removes all elements from the queue.
+   */
+  @Synchronized
+  public fun clear() {
+    queue.clear()
+  }
 }

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/data/source/LogcatDataSource.kt

@@ -2,6 +2,7 @@ package com.ms.square.debugoverlay.internal.data.source
 
 import android.os.Build
 import androidx.annotation.GuardedBy
+import com.ms.square.debugoverlay.Clearable
 import com.ms.square.debugoverlay.LogSource
 import com.ms.square.debugoverlay.internal.InternalDebugOverlayApi
 import com.ms.square.debugoverlay.internal.Logger
@@ -10,13 +11,16 @@ import com.ms.square.debugoverlay.internal.util.throttleLatest
 import com.ms.square.debugoverlay.model.LogEntry
 import kotlinx.coroutines.CoroutineScope
 import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.channels.BufferOverflow
 import kotlinx.coroutines.currentCoroutineContext
 import kotlinx.coroutines.flow.Flow
+import kotlinx.coroutines.flow.MutableSharedFlow
 import kotlinx.coroutines.flow.SharingStarted
 import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.flow
 import kotlinx.coroutines.flow.flowOn
 import kotlinx.coroutines.flow.map
+import kotlinx.coroutines.flow.merge
 import kotlinx.coroutines.flow.stateIn
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.withContext
@@ -36,21 +40,40 @@ internal class LogcatDataSource(
   private val parser: LogcatEntryParser = LogcatEntryParser(),
   private val maxEntries: Int = 300,
 ) : LogSource,
+  Clearable,
   Closeable {
 
   override val sourceName: String = "Logcat"
 
-  private val processLock = Object()
+  private val processLock = Any()
 
   @GuardedBy("processLock")
   private var currentProcess: Process? = null
 
+  private val entries = EvictingQueue<LogEntry>(maxEntries)
+
+  // Drops OS-replayed entries from before the last clear (e.g. when the producer
+  // restarts on panel reopen and `-T N` walks the OS ring buffer).
+  // Wall-clock epoch ms, matching `logcat -v ... epoch`.
+  @Volatile private var clearMarkerMs: Long = 0L
+
+  // Forces a downstream re-read after clear() so the UI sees `[]` instantly,
+  // even when the producer is idle.
+  private val clearSignal = MutableSharedFlow<Unit>(
+    extraBufferCapacity = 1,
+    onBufferOverflow = BufferOverflow.DROP_OLDEST
+  )
+
   /**
-   * Stream logcat entries. Keeps last N entries in memory.
-   * Private StateFlow for direct .value access in [queryLogcatSnapshot].
+   * Producer signal flow. Emits Unit ticks (not data) whenever a new entry is
+   * appended to [entries]. The downstream `.map { entries.toList() }` reads
+   * the queue's current state — the tick payload is irrelevant.
    */
-  private val _logs: StateFlow<List<LogEntry>> = flow {
-    val entries = EvictingQueue<LogEntry>(maxEntries)
+  private val producerSignal: Flow<Unit> = flow {
+    // Each subscription session starts fresh — without this, the hoisted queue
+    // would accumulate duplicates as `logcat -T N` replays the OS ring buffer
+    // on every resubscribe (panel reopen).
+    entries.clear()
     var reader: BufferedReader? = null
     try {
       /**
@@ -67,9 +90,14 @@ internal class LogcatDataSource(
       while (currentCoroutineContext().isActive) {
         // readLine() returns null at end of stream, so exit early if a process dies unexpectedly
         val line = reader.readLine() ?: break
-        parser.parse(line)?.let {
-          entries.add(it)
-          emit(entries)
+        parser.parse(line)?.let { entry ->
+          // Drop OS-replayed entries from before the last clear. `-T N` replays the
+          // last N ring-buffer lines on every subprocess start, including when the
+          // panel reopens after WhileSubscribed cancelled us.
+          // (Rare caveat: a backward system-clock jump could mis-drop a real entry.)
+          if (entry.timestampMs < clearMarkerMs) return@let
+          entries.add(entry)
+          emit(Unit)
         }
       }
     } catch (e: IOException) {
@@ -81,8 +109,20 @@ internal class LogcatDataSource(
       safeDestroyProcess()
     }
   }
-    .throttleLatest(500.milliseconds)
-    .map { it.toList() }
+
+  /**
+   * Stream logcat entries. Keeps last N entries in memory.
+   * Private StateFlow for direct .value access in [queryLogcatSnapshot].
+   *
+   * `throttleLatest` is applied only to `producerSignal` so noisy producers
+   * are rate-limited, while `clearSignal` flows straight through merge to
+   * the downstream `.map` — making clear() visually instant.
+   */
+  private val _logs: StateFlow<List<LogEntry>> = merge(
+    producerSignal.throttleLatest(500.milliseconds),
+    clearSignal
+  )
+    .map { entries.toList() }
     .flowOn(Dispatchers.IO)
     .stateIn(
       scope,
@@ -93,15 +133,22 @@ internal class LogcatDataSource(
   /** Public API for [LogSource] interface. */
   override val logs: Flow<List<LogEntry>> = _logs
 
+  override fun clear() {
+    clearMarkerMs = System.currentTimeMillis()
+    entries.clear()
+    clearSignal.tryEmit(Unit)
+  }
+
   /**
    * Returns a snapshot of logcat logs for bug reports.
    * Uses cached value if streaming was active (debug panel was viewed), otherwise captures directly.
    */
   suspend fun queryLogcatSnapshot(): List<LogEntry> {
     val cached = _logs.value
     if (cached.isNotEmpty()) return cached
-
-    return captureLogcatOnce()
+    // drop anything captured before the last clear so a "clear → close panel → bug report" flow
+    // doesn't resurface pre-clear lines.
+    return captureLogcatOnce().filter { it.timestampMs >= clearMarkerMs }
   }
 
   private suspend fun captureLogcatOnce(): List<LogEntry> = withContext(Dispatchers.IO) {

debugoverlay-core/src/main/kotlin/com/ms/square/debugoverlay/internal/ui/DebugPanelDialog.kt

@@ -10,6 +10,7 @@ import androidx.compose.foundation.layout.padding
 import androidx.compose.foundation.layout.size
 import androidx.compose.material.icons.Icons
 import androidx.compose.material.icons.filled.BugReport
+import androidx.compose.material.icons.filled.ClearAll
 import androidx.compose.material.icons.filled.Close
 import androidx.compose.material3.CircularProgressIndicator
 import androidx.compose.material3.ExperimentalMaterial3Api
@@ -131,6 +132,7 @@ internal fun DebugPanelDialog(onDismiss: () -> Unit) {
 @OptIn(ExperimentalMaterial3Api::class)
 @Composable
 private fun DebugPanelTopAppBar(
+  overlayDataRepository: DebugOverlayDataRepository = DebugOverlay.overlayDataRepository,
   bugReportGenerator: BugReportGenerator = DebugOverlay.bugReportGenerator,
   snackBarHostState: SnackbarHostState,
   onDismiss: () -> Unit,
@@ -150,6 +152,9 @@ private fun DebugPanelTopAppBar(
       )
     },
     actions = {
+      ClearLogsButton(
+        onClick = { overlayDataRepository.clearAllLogs() }
+      )
       BugReportButton(
         isCapturing = isCapturing,
         draftCount = draftCount,
@@ -190,6 +195,20 @@ private fun DebugPanelTopAppBar(
   )
 }
 
+@Composable
+private fun ClearLogsButton(onClick: () -> Unit) {
+  val description = stringResource(R.string.debugoverlay_clear_logs_content_description)
+  IconButton(
+    onClick = onClick,
+    modifier = Modifier.semantics { contentDescription = description }
+  ) {
+    Icon(
+      imageVector = Icons.Default.ClearAll,
+      contentDescription = null // Handled by IconButton semantics
+    )
+  }
+}
+
 @Composable
 private fun BugReportButton(isCapturing: Boolean, draftCount: Int, onClick: () -> Unit) {
   // Dynamic accessibility description matching FAB behavior

debugoverlay-core/src/main/res/values/strings.xml

@@ -3,6 +3,7 @@
   <!-- Debug Panel -->
   <string name="debugoverlay_debug_panel">Debug Panel</string>
   <string name="debugoverlay_close">Close</string>
+  <string name="debugoverlay_clear_logs_content_description">Clear collected logs</string>
 
   <!-- Tab Titles -->
   <string name="debugoverlay_tab_log">Log</string>

debugoverlay-extension-okhttp/src/main/kotlin/com/ms/square/debugoverlay/extension/okhttp/DebugOverlayNetworkInterceptor.kt

@@ -1,5 +1,6 @@
 package com.ms.square.debugoverlay.extension.okhttp
 
+import com.ms.square.debugoverlay.Clearable
 import com.ms.square.debugoverlay.DebugOverlay
 import com.ms.square.debugoverlay.NetworkRequestSource
 import com.ms.square.debugoverlay.extension.okhttp.internal.isProbablyUtf8
@@ -93,7 +94,8 @@ public class DebugOverlayNetworkInterceptor(
   private val queryParamsNameToRedact: Set<String> = DEFAULT_QUERY_PARAMS_REDACT,
   private val maxBodySize: Long = DEFAULT_MAX_BODY_SIZE,
 ) : Interceptor,
-  NetworkRequestSource {
+  NetworkRequestSource,
+  Clearable {
 
   private val recentRequests = EvictingQueue<NetworkRequest>(maxStoredRequests)
   private val _requests = MutableStateFlow<List<NetworkRequest>>(emptyList())
@@ -436,6 +438,11 @@ public class DebugOverlayNetworkInterceptor(
     }
   }
 
+  override fun clear() {
+    recentRequests.clear()
+    _requests.update { emptyList() }
+  }
+
   private fun redactUrl(url: HttpUrl): HttpUrl {
     if (queryParamsNameToRedact.isEmpty() || url.querySize == 0) {
       return url

debugoverlay-extension-okhttp/src/test/kotlin/com/ms/square/debugoverlay/extension/okhttp/DebugOverlayNetworkInterceptorTest.kt

@@ -284,4 +284,24 @@ class DebugOverlayNetworkInterceptorTest {
     val capturedRequest = requests.first()
     assertThat(capturedRequest.responseBody).contains("failed to read response body")
   }
+
+  @Test
+  fun `clear empties captured requests and subsequent collection still works`() = runTest {
+    mockWebServer.enqueue(MockResponse().setResponseCode(200).setBody("first"))
+    mockWebServer.enqueue(MockResponse().setResponseCode(200).setBody("second"))
+
+    client.newCall(Request.Builder().url(mockWebServer.url("/first")).get().build())
+      .execute().close()
+    assertThat(interceptor.requests.first()).hasSize(1)
+
+    interceptor.clear()
+
+    assertThat(interceptor.requests.first()).isEmpty()
+
+    client.newCall(Request.Builder().url(mockWebServer.url("/second")).get().build())
+      .execute().close()
+    val afterClear = interceptor.requests.first()
+    assertThat(afterClear).hasSize(1)
+    assertThat(afterClear.first().url).contains("/second")
+  }
 }