feat: Logwood — production-grade logging library for Android

[alexfin90]

Logwood — Production-Grade Logging Library for Android

Unified configuration, privacy-first, modular sinks, runtime control.

Why

The project has Timber 5.0.1 declared in every module (via convention plugin) but never initialized (//TODO Timber in CvApplication). Rather than writing yet another custom Timber.Tree, we want a production-grade logging pipeline with:

• Modular sinks: each output (Logcat, Crashlytics, Sentry, File, RingBuffer) is a pluggable LogSink
• Runtime policy control: change log priority, enable/disable, sampling, tag filtering — without recompiling
• Backend-agnostic non-fatal reporting: reportNonFatal() API decoupled from Firebase
• Privacy-first: PII redaction before any sink, in-memory ring buffer only, no permanent storage by default
• Simple DSL for configuration

Strategy: Step 1 as core:logging module inside CvShowcase, stabilized with tests, then extracted to a standalone OSS repo (logwood-android).

---

Architecture

Pipeline

App / Feature Module
        │
        ▼
   Logwood.log(...)                    ← direct API
   Logwood.reportNonFatal(...)         ← non-fatal reporting
        │
   Timber.d() / Timber.e()            ← or via Timber bridge
        │
        ▼
   LogwoodTimberTree                   ← converts Timber call to LogEntry
        │
        ▼
   Redaction                           ← DefaultRedaction scrubs PII
        │
        ▼
   LogPolicy (runtime)                 ← AtomicReference, thread-safe
   minPriority? enabled? sampleRate?
   tagsBlocklist? remoteDebugSession?
        │
   ┌────┴──────┬───────────────┬──────────────────┐
   ▼           ▼               ▼                  ▼
LogcatSink  RingBufferSink  CrashlyticsSink    (future sinks)
   │           │               │
   ▼           ▼               ▼
Per-sink     Per-sink        Per-sink
policy       policy          policy

For reportNonFatal(), a direct path bypasses the log pipeline:

Logwood.reportNonFatal(throwable, attrs, fingerprint)
  → sinks.filterIsInstance<CrashReporterSink>()
  → CrashReporterSink.reportNonFatal(NonFatalReport)

Module Structure

core:logging (NEW Android library)
  depends on: timber (already in convention plugin)
  ZERO Firebase/Hilt dependencies
  │
  ├── Logwood.kt                        — entry point + DSL
  ├── LogEntry.kt                       — data class (priority, tag, message, throwable, timestamp, thread)
  ├── LogPolicy.kt                      — data class + MutableLogPolicy (AtomicReference)
  ├── LogSink.kt                        — base interface
  ├── CrashReporterSink.kt              — extends LogSink + reportNonFatal
  ├── NonFatalReport.kt                 — model (throwable + attributes + fingerprint)
  ├── exception/
  │   └── NonFatalException.kt          — base exception with code field
  ├── pipeline/
  │   └── LogPipeline.kt                — orchestrator: redact → policy → dispatch
  ├── sink/
  │   ├── LogcatSink.kt                 — android.util.Log output
  │   └── InMemoryRingBufferSink.kt     — circular buffer, thread-safe, exportable
  ├── redaction/
  │   ├── Redaction.kt                  — fun interface
  │   ├── NoOpRedaction.kt
  │   └── DefaultRedaction.kt           — email, phone, IP, token, GPS regex
  ├── timber/
  │   └── LogwoodTimberTree.kt          — Timber.Tree bridge
  └── export/
      └── RingBufferExporter.kt         — plain text + JSON lines

app (existing)
  depends on: core:logging
  │
  ├── src/real/kotlin/.../logging/
  │   ├── CrashlyticsSink.kt            — implements CrashReporterSink via Firebase
  │   └── LoggingModule.kt              — Hilt: provides sinks
  ├── src/mock/kotlin/.../logging/
  │   └── LoggingModule.kt              — Hilt: no Crashlytics
  └── CvShowcaseApplication.kt          — Logwood.install {}

---

DSL API

Installation

// In CvApplication.onCreate()
Logwood.install {
    policy {
        minPriority = if (BuildConfig.DEBUG) Log.VERBOSE else Log.WARN
        enabled = true
        sampleRate = 1.0f
        tagsBlocklist = setOf("NoisyTag", "NetworkPoll")
    }

    sinks {
        logcat()
        ringBuffer(maxEntries = 500)
        crashlytics(myCrashlyticsSink, nonFatalMinPriority = Log.WARN)
    }

    redaction(DefaultRedaction())
}

Non-Fatal Reporting

// Direct API (no Timber dependency needed)
Logwood.reportNonFatal(
    throwable = NetworkNonFatalException(
        code = "PAYMENT_FAILED",
        message = "Timeout on checkout",
        httpStatusCode = 504,
    ),
    attributes = mapOf("userId" to userId, "screen" to "checkout"),
    fingerprint = "payment-flow-error",
)

// Or via Timber (backward-compatible)
Timber.e(NonFatalException(code = "GENERIC", message = "..."))

Runtime Toggle

// Enable debug logging for a diagnostic session
Logwood.updatePolicy { copy(minPriority = Log.DEBUG, remoteDebugSession = true) }

// Restore original policy
Logwood.resetPolicy()

Ring Buffer Export

val logDump: String = Logwood.exportRingBuffer()
// Attachable to email, share sheet, or manual upload

---

Key Interfaces

LogEntry

data class LogEntry(
    val priority: Int,
    val tag: String?,
    val message: String,
    val throwable: Throwable?,
    val timestamp: Long = System.currentTimeMillis(),
    val threadName: String = Thread.currentThread().name,
)

LogPolicy

data class LogPolicy(
    val minPriority: Int = Log.WARN,
    val enabled: Boolean = true,
    val sampleRate: Float = 1.0f,
    val tagsAllowlist: Set<String> = emptySet(),
    val tagsBlocklist: Set<String> = emptySet(),
    val remoteDebugSession: Boolean = false,
)

When remoteDebugSession = true, the effective min priority overrides to VERBOSE regardless of minPriority. Thread-safe via MutableLogPolicy backed by AtomicReference. resetPolicy() restores the original policy set at install time.

LogSink + CrashReporterSink

interface LogSink {
    val name: String
    val policyOverride: LogPolicy? get() = null
    fun log(entry: LogEntry)
    fun flush() {}
}

interface CrashReporterSink : LogSink {
    fun reportNonFatal(report: NonFatalReport)
}

NonFatalException (in exception/ package)

open class NonFatalException(
    open val code: String,
    override val message: String,
    cause: Throwable? = null,
) : Exception(message, cause)

Extensible for domain-specific exceptions:

class NetworkNonFatalException(
    override val code: String,
    override val message: String,
    val httpStatusCode: Int,
) : NonFatalException(code, message)

NonFatalReport

data class NonFatalReport(
    val throwable: Throwable,
    val attributes: Map<String, String> = emptyMap(),
    val fingerprint: String? = null,
)

Redaction

fun interface Redaction {
    fun redact(entry: LogEntry): LogEntry
}

DefaultRedaction scrubs PII with regex patterns (email, phone, IP, tokens, GPS coordinates) before any sink receives the log entry. This is a safety net — even if a developer accidentally logs PII, sinks never receive it in clear text.

---

Design Decisions

Decision	Rationale
object Logwood (no Hilt)	Logging is global by nature. The app uses Hilt to build sinks, then passes them to install {}. core:logging stays Hilt-free and extractable.
AtomicReference for policy	Reads vastly outnumber writes. Lock-free for read, CAS for write. No suspend/Mutex needed in hot path.
ReentrantReadWriteLock for ring buffer	Fixed-size with wrapping semantics. Allows concurrent snapshots without blocking writers.
remoteDebugSession in policy	Global override to VERBOSE without touching minPriority. Single flag activatable from Remote Config.
resetPolicy()	Returns to the original policy after a debug session. MutableLogPolicy stores the original.
NonFatalReport separate from NonFatalException	Report has attributes and fingerprint that don't belong on the exception. Separates the model from the throwable.
NonFatalException in exception/ package inside core:logging	It's a library concept, not app domain. Travels with the module when extracted to OSS. Dedicated package keeps it confined.
Nested DSL: policy {} + sinks {}	Clean separation between policy config and output config. More readable than flat parameters.
Redaction before sinks	PII scrubbed once, not per-sink. Guarantees no sink receives cleartext PII.

---

Privacy & Security

• Ring buffer: in-memory only, not persisted across sessions
• FileSink (future): will use getFilesDir() — never external storage
• DefaultRedaction: applied BEFORE any sink receives data
• No automatic upload by design: every export is user-initiated or event-triggered (non-fatal only)
• remoteDebugSession: should be protected by an authenticated flag (e.g., Firebase Remote Config with user-specific rules)
• Sampling: reduces data volume in production

---

Implementation Plan

Step 1A: Gradle Infrastructure

1. Add loggingModuleName=logging to gradle.properties
2. Add loggingModuleName property to ProjectExtensions.kt (build-logic)
3. Add include(":core:logging") to settings.gradle.kts
4. Create core/logging/build.gradle.kts with cvshowcase-library plugin

Step 1B: Interfaces and Models

5. LogEntry.kt
6. LogPolicy.kt + MutableLogPolicy
7. LogSink.kt
8. CrashReporterSink.kt
9. exception/NonFatalException.kt
10. NonFatalReport.kt
11. Redaction.kt, NoOpRedaction.kt, DefaultRedaction.kt

Step 1C: Pipeline and Sinks

12. LogPipeline.kt
13. LogcatSink.kt
14. InMemoryRingBufferSink.kt
15. RingBufferExporter.kt

Step 1D: Timber Bridge + Entry Point

16. LogwoodTimberTree.kt
17. Logwood.kt + LogwoodBuilder + SinkBuilder

Step 1E: Unit Tests

18. LogPolicyTest.kt — accepts() with minPriority, enabled, sampleRate, tags, remoteDebugSession
19. MutableLogPolicyTest.kt — thread-safety, reset()
20. LogPipelineTest.kt — redaction, global policy, per-sink policy, dispatchNonFatal
21. InMemoryRingBufferSinkTest.kt — wrapping, snapshot ordering, clear, concurrency
22. DefaultRedactionTest.kt — email, phone, IP, token, GPS, edge cases
23. LogwoodTimberTreeTest.kt — correct dispatch
24. RingBufferExporterTest.kt — plain text and JSON format
25. LogwoodInstallTest.kt — DSL, Timber tree planted, policy, resetPolicy

Step 1F: App Integration

26. app/src/real/kotlin/.../CrashlyticsSink.kt
27. app/src/real/kotlin/.../LoggingModule.kt (Hilt)
28. app/src/mock/kotlin/.../LoggingModule.kt (Hilt, no Crashlytics)
29. Add implementation(project(":core:logging")) to app/build.gradle.kts
30. Update CvShowcaseApplication.kt with Logwood.install {}
31. Uncomment ProGuard rules for SourceFile + LineNumber

Phase 2 (future): DevSettings + Remote Toggle

• feature:devsettings module with Compose UI
• FirebaseRemoteLogToggle (Remote Config + User Property for per-device targeting)
• LocalPolicyOverride (SharedPreferences)
• DevSettings route + deep link cvshowcase://devsettings

Phase 3 (future): OSS Extraction

• New repo logwood-android on GitHub
• Multi-module: logwood-core, logwood-firebase-crashlytics, logwood-timber-bridge
• Maven Central / JitPack publishing
• README, sample app, CI

---

Build Variant Matrix

Variant	Active Sinks	Crashlytics	Logcat	RingBuffer
mockDebug	Logcat + RingBuffer	No	VERBOSE+	Yes
realDebug	Logcat + RingBuffer + Crashlytics	Yes	VERBOSE+	Yes
mockRelease	Logcat + RingBuffer	No	WARN+	Yes
realRelease	Logcat + RingBuffer + Crashlytics	Yes	WARN+	Yes

Any variant can change policy at runtime via Logwood.updatePolicy {} or remoteDebugSession = true.

---

Verification Checklist

• ./gradlew build — all variants compile
• ./gradlew :core:logging:test — all unit tests pass
• ./gradlew test — existing tests not broken
• Debug: Timber.d("test") appears in Logcat
• Release: Timber.d("test") does NOT appear, Timber.w("test") does
• Runtime toggle: Logwood.updatePolicy { copy(minPriority = Log.VERBOSE) } → debug logs appear
• resetPolicy() restores original policy
• Logwood.exportRingBuffer() returns last N logs
• Logwood.reportNonFatal(NonFatalException("CODE", "msg")) → appears in Crashlytics (real only)
• Redaction: log with email/phone → [EMAIL], [PHONE] in all sinks
• remoteDebugSession = true → all levels pass even in release
• Thread safety: concurrent tests on MutableLogPolicy and InMemoryRingBufferSink pass

---

Differentiation

Aspect	Timber (raw)	Timber + custom Tree	Logwood
Unified DSL configuration	-	-	policy {} + sinks {}
Runtime toggle without recompile	-	-	updatePolicy / resetPolicy
Backend-agnostic non-fatal	-	Crashlytics only	CrashReporterSink interface
Local ring buffer	-	-	InMemoryRingBufferSink
Built-in PII redaction	-	-	DefaultRedaction
Sampling rate	-	-	sampleRate 0.0..1.0
Remote debug session	-	-	remoteDebugSession flag
Diagnostics export	-	-	exportRingBuffer()
Separate core/firebase modules	N/A	-	logwood-core / logwood-crashlytics

[alexfin90]

@claude implement it and open pull request

[claude]

Claude encountered an error —— View job

---

Implementing Logwood — Production-Grade Logging Library

• Analyze issue and plan implementation
• Explore existing codebase structure
• Step 1A: Gradle infrastructure (core:logging module setup)
• Step 1B: Interfaces and models (LogEntry, LogPolicy, LogSink, etc.)
• Step 1C: Pipeline and sinks (LogPipeline, LogcatSink, InMemoryRingBufferSink, RingBufferExporter)
• Step 1D: Timber bridge + entry point (LogwoodTimberTree, Logwood.kt)
• Step 1E: Unit tests
• Step 1F: App integration (Hilt modules, CvShowcaseApplication)
• Commit and push all changes
• Open pull request

Key design decisions:

• core:logging uses cvshowcase-library plugin (includes Timber, no Firebase/Hilt code in library itself)
• NonFatalException defined fresh in core:logging (existing domain one kept for backward compatibility)
• Hilt @IntoSet multibindings aggregate sinks across flavors
• BaseLoggingModule (main) provides LogcatSink + InMemoryRingBufferSink; real LoggingModule adds CrashlyticsSink
• Logwood.install {} automatically plants LogwoodTimberTree, replacing plantTimberTree()

[claude]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.

[claude]

Claude finished @alexfin90's task in 12m 24s —— View job • claude/issue-9-20260330-1202 • [Create PR ➔](https://github.com/alexfin90/CVshowcase/compare/main...claude/issue-9-20260330-1202?quick_pull=1&title=feat%3A%20Logwood%20%E2%80%94%20production-grade%20logging%20library%20for%20Android&body=Implements%20the%20full%20Logwood%20logging%20pipeline%20described%20in%20%239.%0A%0A%23%23%20What%27s%20included%0A%0A**New%20%60core%3Alogging%60%20module**%20(zero%20Hilt%2FFire%20base%20dependencies%3A%0A-%20%60LogEntry%60%2C%20%60LogPolicy%60%2C%20%60MutableLogPolicy%60%20(AtomicReference%2C%20thread-safe)%0A-%20%60LogSink%60%20%2F%20%60CrashReporterSink%60%20interfaces%0A-%20%60NonFatalReport%60%20%2B%20%60exception%2FNonFatalException%60%0A-%20%60DefaultRedaction%60%20(email%2C%20phone%2C%20IP%2C%20token%2C%20GPS%20regex)%0A-%20%60LogPipeline%60%20(redact%20%E2%86%92%20global%20policy%20%E2%86%92%20per-sink%20policy%20%E2%86%92%20dispatch)%0A-%20%60LogcatSink%60%2C%20%60InMemoryRingBufferSink%60%20(ReentrantReadWriteLock)%0A-%20%60RingBufferExporter%60%20(plain%20text%20%2B%20JSON%20lines)%0A-%20%60LogwoodTimberTree%60%20(Timber.Tree%20bridge)%0A-%20%60Logwood%60%20DSL%20entry%20point%0A%0A**8%20unit%20test%20files**%20covering%20policy%2C%20pipeline%2C%20redaction%2C%20ring%20buffer%2C%20exporter%2C%20Timber%20tree%2C%20and%20install%20DSL%0A%0A**App%20integration**%3A%0A-%20Replaced%20%60CvShowcaseDebugTree%60%20%2F%20%60CvShowcaseReleaseTree%60%20with%20%60Logwood.install%20%7B%7D%60%0A-%20Debug%3A%20Logcat%20%2B%20RingBuffer%2C%20VERBOSE%2B%2C%20DefaultRedaction%0A-%20Release%3A%20Logcat%20%2B%20RingBuffer%20%2B%20CrashlyticsSink%2C%20WARN%2B%2C%20DefaultRedaction%0A-%20%60CrashlyticsSink%60%20handles%20both%20domain%20and%20logging%20NonFatalException%20types%0A%0ACloses%20%239%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode))

---

Implementing Logwood — Production-Grade Logging Library

• Gather context and explore codebase structure
• Step 1A: Gradle Infrastructure (module setup)
• Step 1B: Interfaces and Models (LogEntry, LogPolicy, LogSink, NonFatalReport, redaction classes)
• Step 1C: Pipeline and Sinks (LogPipeline, LogcatSink, InMemoryRingBufferSink, RingBufferExporter)
• Step 1D: Timber Bridge + Entry Point (LogwoodTimberTree, Logwood DSL)
• Step 1E: Unit Tests (LogPolicy, MutableLogPolicy, LogPipeline, RingBuffer, Redaction, Timber tree, Exporter, Install)
• Step 1F: App Integration (CrashlyticsSink, TimberConfiguration, app wired up)
• Commit and push changes
• Open pull request

|