Getting Started

Requirements

Installation

[versions]
aelog = "1.1.7"

[libraries]
aelog-logs      = { module = "io.github.abdo-essam:ae-log-logs", version.ref = "aelog" }
aelog-network   = { module = "io.github.abdo-essam:ae-log-network", version.ref = "aelog" }
aelog-analytics = { module = "io.github.abdo-essam:ae-log-analytics", version.ref = "aelog" }
aelog-crashes   = { module = "io.github.abdo-essam:ae-log-crashes", version.ref = "aelog" }

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation(libs.aelog.logs)
            implementation(libs.aelog.network)
            implementation(libs.aelog.analytics)
            implementation(libs.aelog.crashes)
        }
    }
}

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.abdo-essam:ae-log-logs:1.1.7")
            implementation("io.github.abdo-essam:ae-log-network:1.1.7")
            implementation("io.github.abdo-essam:ae-log-analytics:1.1.7")
            implementation("io.github.abdo-essam:ae-log-crashes:1.1.7")
        }
    }
}

Verify Installation

import com.ae.log.AELog

fun main() {
    // Simply check if AELog is accessible
    AELog.isEnabled = true
    println("AELog is accessible and enabled: ${AELog.isEnabled}")
}

AELog is accessible and enabled: true

Next Steps

• Quick Start Guide — Integrate into your app in 5 minutes
• Configuration — Customize behavior and appearance
• Custom Plugins — Build your own debug panels

Quick Start

Get up and running in just a few seconds.

1. Zero-Config (Automatic Setup)

AELog features zero-config auto-initialisation on both Android and iOS. Just add the dependencies for the plugins you want, and they automatically register themselves. No initialization code is required in your application!

2. Custom Configuration (Optional)

To disable the floating trigger notch globally (across all screens), set the static property AELog.showNotch at your app entry point (e.g. Application.onCreate() on Android):

// Disable the floating notch globally (defaults to true)
AELog.showNotch = false

3. Drop in the Overlay

Add AELogOverlay() as a sibling anywhere in your root composable — no wrapping required:

@Composable
fun App() {
    AELogOverlay() // ← Renders floating center-right notch + inspector panel as a Popup above your UI
    MaterialTheme {
        YourAppContent()
    }
}

To disable in release builds: AELog.isEnabled = BuildConfig.DEBUG
To hide the floating notch trigger locally but still open the panel programmatically: AELogOverlay(showNotch = false) then AELog.show()

3. Start Logging

Use the discoverable static APIs. AELog handles everything else behind the scenes.

// 1. Logs (with automatic tag derivation from the calling class)
AELog.log.i("App launched!")
AELog.log.d("Auth", "Token refreshed") // Or specify an explicit tag

// 2. Network (handled automatically via interceptors)
// val client = HttpClient { install(AELogKtorInterceptor) }

// 3. Analytics
AELog.analytics.logEvent("button_tap")

// 4. Crashes (manually record non-fatal exceptions)
try {
    performDangerousTask()
} catch (t: Throwable) {
    AELog.crashes.recordNonFatal(t)
}

Show / Hide the Overlay

The overlay can be triggered by:

• Floating Notch — the Dynamic Island-style pill at the top of the screen (shown by default)
• Programmatically via AELog.show() / AELog.hide() from anywhere in your code
• Custom triggers — wire AELog.show() to a shake gesture, debug settings, or any other event

Configuration

AELog is designed to be "zero-config" by default, but provides hooks to customize both data collection and UI behavior.

Core Configuration (Data & UI Globals)

You can toggle global features like the floating notch trigger or enable/disable the logger using properties directly on AELog:

// Disable the floating notch globally (across XML & Compose screens)
AELog.showNotch = false

// Enable or disable the entire library programmatically
AELog.isEnabled = BuildConfig.DEBUG

UI Configuration

Control whether the floating notch is shown, or hide it and trigger the overlay programmatically:

// Default — shows the vertical notch trigger on the right side of the screen
AELogOverlay()

// Hidden notch trigger — open programmatically from custom buttons, shake gestures, etc.
AELogOverlay(showNotch = false)
// Then from anywhere in your codebase:
AELog.show()
AELog.hide()

// Disable the entire library (e.g. in release builds)
AELog.isEnabled = BuildConfig.DEBUG

Plugins Overview

AELog uses a plugin architecture. Each plugin adds a dedicated tab to the AELog overlay panel. The library itself is just a host — plugins are what make it useful.

How Plugins Work

When you call AELog.install(...), the library:

1. Installs each plugin and calls its onAttach() lifecycle hook
2. Renders UIPlugin instances as tabs in the overlay panel
3. Provides each plugin with access to a coroutine scope and sibling plugins via PluginContext

Built-in Plugins

Logs Inspector

Browse console output with search capabilities and filter logs by severity level.

Network Inspector

Inspect Ktor and OkHttp HTTP request/response payloads, status codes, and headers.

Analytics Tracker

View analytics events, screen views, and user property parameters as they trigger in real-time.

Crash Reporter

Review local fatal stack traces and persisted exception reports directly on the test device.

Plugin Types

UIPlugin

Renders a tab inside the AELog panel. Ideal for visually inspecting data (logs, network calls, feature flags, database records, etc.). UI plugins now own their entire layout inside the Content() composable (e.g. sticky search bars, custom headers, and scrollable lists).

Plugin (Headless)

A headless background collector with no UI. Simply implement the standard Plugin interface directly. Use it for crash collectors, performance samplers, background interceptors, or anything that needs to observe data or listen to event signals without a dedicated visual tab.

Installing Plugins

// Auto-registered on Android via ContentProvider — no code needed!
// But if you are on other platforms (like iOS) or adding custom plugins:

AELog.install(MyCustomPlugin())

Plugin Lifecycle

Each hook has a clear responsibility:

Creating Custom Plugins

Creating Custom Plugins

AELog is designed to be extended. You can create two types of plugins:

Plugin Types

Creating a UI Plugin

Step 1: Implement UIPlugin

class FeatureFlagsPlugin : UIPlugin {
    // override val id = "feature_flags" // Optional: Defaults to qualified class name
    override val name = "Flags"
    override val icon: @Composable () -> Unit = { Icon(Icons.Default.Flag, null) }

    // Override badgeCount only when your plugin tracks a meaningful live count.
    // Omit it entirely if you don't need a badge — the default shows nothing.
    private val _badgeCount = MutableStateFlow(0)
    override val badgeCount: StateFlow<Int> = _badgeCount

    private var context: PluginContext? = null

    // Called once when installed
    override fun onAttach(context: PluginContext) {
        this.context = context
        _badgeCount.value = getFlags().size
    }

    // Called when user taps "Clear All"
    override fun onClear() {
        resetFlags()
        _badgeCount.value = 0
    }

    // Called when plugin is uninstalled
    override fun onDetach() {
        context = null
    }

    // Main content rendered in the AELog panel (owns entire layout!)
    @Composable
    override fun Content(modifier: Modifier) {
        val flags = remember { getFlags() }

        Column(modifier = modifier.fillMaxSize()) {
            // Sticky search/filter bar and action headers go directly inside Content()!
            Row(
                modifier = Modifier.fillMaxWidth().padding(8.dp),
                horizontalArrangement = Arrangement.SpaceBetween
            ) {
                Text("Toggle feature flags for testing", style = MaterialTheme.typography.bodySmall)
                IconButton(onClick = { resetAllFlags() }) {
                    Icon(Icons.Default.Refresh, "Reset all")
                }
            }

            LazyColumn(modifier = Modifier.weight(1f)) {
                items(flags) { flag ->
                    FlagRow(
                        name = flag.name,
                        enabled = flag.enabled,
                        onToggle = { toggleFlag(flag.id) }
                    )
                }
            }
        }
    }
}

Step 2: Install the Plugin

// Add your custom plugin alongside the auto-registered built-ins
AELog.install(FeatureFlagsPlugin())

Step 3: Done!

Your plugin now appears as a tab in the AELog panel.

Creating a Headless Plugin

class PerformancePlugin : Plugin {
    // override val id = "performance" // Optional: Defaults to qualified class name
    override val name = "Performance"

    private val _metrics = MutableStateFlow<List<Metric>>(emptyList())
    val metrics: StateFlow<List<Metric>> = _metrics.asStateFlow()

    override fun onAttach(context: PluginContext) {
        startCollecting(context.scope)
    }

    override fun onDetach() {
        stopCollecting()
    }

    fun recordMetric(name: String, durationMs: Long) {
        _metrics.update { it + Metric(name, durationMs) }
    }
}

// Usage
val perfPlugin = AELog.getPlugin<PerformancePlugin>()
perfPlugin?.recordMetric("api_call", 250L)

Plugin Lifecycle

Best Practices

• Keep plugins focused — one responsibility per plugin
• Use StateFlow — all reactive data should use StateFlow
• Minimize main-thread work — heavy computation goes in background coroutine scopes
• Clean up in onDetach — cancel background tasks and release state
• Test independently — plugins can be unit-tested fully in KMP commonMain

Logging Integrations

AELog works with any logging library. Just forward logs to the static AELog.log methods.

Kermit

import co.touchlab.kermit.LogWriter
import co.touchlab.kermit.Severity
import com.ae.log.AELog

class AELogKermitWriter : LogWriter() {
    override fun log(
        severity: Severity,
        message: String,
        tag: String,
        throwable: Throwable?
    ) {
        when (severity) {
            Severity.Verbose -> AELog.log.v(tag, message, throwable)
            Severity.Debug -> AELog.log.d(tag, message, throwable)
            Severity.Info -> AELog.log.i(tag, message, throwable)
            Severity.Warn -> AELog.log.w(tag, message, throwable)
            Severity.Error -> AELog.log.e(tag, message, throwable)
            Severity.Assert -> AELog.log.wtf(tag, message, throwable)
        }
    }
}

// Setup
Logger.addLogWriter(AELogKermitWriter())

Napier

import io.github.aakira.napier.Antilog
import io.github.aakira.napier.LogLevel
import com.ae.log.AELog

class AELogNapierAntilog : Antilog() {
    override fun performLog(
        priority: LogLevel,
        tag: String?,
        throwable: Throwable?,
        message: String?
    ) {
        val resolvedTag = tag ?: "Napier"
        val resolvedMsg = message ?: ""
        when (priority) {
            LogLevel.VERBOSE -> AELog.log.v(resolvedTag, resolvedMsg, throwable)
            LogLevel.DEBUG -> AELog.log.d(resolvedTag, resolvedMsg, throwable)
            LogLevel.INFO -> AELog.log.i(resolvedTag, resolvedMsg, throwable)
            LogLevel.WARNING -> AELog.log.w(resolvedTag, resolvedMsg, throwable)
            LogLevel.ERROR -> AELog.log.e(resolvedTag, resolvedMsg, throwable)
            LogLevel.ASSERT -> AELog.log.wtf(resolvedTag, resolvedMsg, throwable)
        }
    }
}

// Setup
Napier.base(AELogNapierAntilog())

Timber (Android)

import timber.log.Timber
import com.ae.log.AELog

class AELogTimberTree : Timber.Tree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        val resolvedTag = tag ?: "Timber"
        when (priority) {
            android.util.Log.VERBOSE -> AELog.log.v(resolvedTag, message, t)
            android.util.Log.DEBUG -> AELog.log.d(resolvedTag, message, t)
            android.util.Log.INFO -> AELog.log.i(resolvedTag, message, t)
            android.util.Log.WARN -> AELog.log.w(resolvedTag, message, t)
            android.util.Log.ERROR -> AELog.log.e(resolvedTag, message, t)
            android.util.Log.ASSERT -> AELog.log.wtf(resolvedTag, message, t)
            else -> AELog.log.d(resolvedTag, message, t)
        }
    }
}

// Setup
Timber.plant(AELogTimberTree())

Ktor Client Logging

import io.ktor.client.*
import io.ktor.client.plugins.logging.*
import com.ae.log.AELog

val client = HttpClient {
    install(Logging) {
        logger = object : Logger {
            override fun log(message: String) {
                // Forward to AELog
                AELog.log.d("HTTP", message)
            }
        }
        level = LogLevel.ALL
    }
}

Direct Usage (No Library)

// Use the static shorthands
AELog.log.i("MyApp", "App started")
AELog.log.e("Auth", "Login failed", error)

Changelog

All notable changes and releases of AELog are detailed below in our interactive project roadmap.

Contributing to AELog

First off, thank you for considering contributing! 🎉

Table of Contents

• Code of Conduct
• Getting Started
• Development Setup
• How to Contribute
• Pull Request Process
• Coding Standards
• Architecture Overview

Code of Conduct

This project follows our Code of Conduct. By participating, you agree to uphold this code.

Getting Started

Prerequisites

• JDK 17+
• Android Studio Ladybug or later / Fleet
• Xcode 15+ (for iOS targets)
• Kotlin 2.2.0+

Development Setup

# Clone the repository
git clone https://github.com/abdo-essam/AELog.git
cd AELog

# Build the project
./gradlew build

# Run tests
./gradlew allTests

# Run the sample app (Android)
./gradlew :sample:composeApp:installDebug

# Check code formatting
./gradlew spotlessCheck

# Fix code formatting
./gradlew spotlessApply

# Generate API docs
./gradlew dokkaGeneratePublicationHtml

# Verify binary compatibility
./gradlew apiCheck

How to Contribute

🐛 Reporting Bugs

• Use the Bug Report template
• Include: KMP version, platform, steps to reproduce, expected vs actual behavior

💡 Suggesting Features

• Use the Feature Request template
• Describe the use case, not just the solution

🔧 Submitting Changes

• Fork the repository
• Create a feature branch: git checkout -b feat/my-feature
• Make your changes
• Add/update tests
• Run the full check: ./gradlew check
• Commit using Conventional Commits
• Push and open a Pull Request

Pull Request Process

• Fill out the PR template completely
• Ensure CI passes — all checks must be green
• One approval required from a maintainer
• Squash merge is preferred for clean history
• Update CHANGELOG.md under [Unreleased]

Coding Standards

Kotlin Style

• Follow Kotlin Coding Conventions
• Use explicitApi() — all public APIs need visibility modifiers
• Mark internal APIs with internal keyword
• KDoc on all public classes, functions, and properties

Commit Conventions

We use Conventional Commits:

feat: add network inspection plugin
fix: resolve theme bleed into host app
docs: update plugin creation guide
test: add LogStorage unit tests
refactor: extract log filtering to separate class
chore: update Kotlin to 2.3.0
perf: cache LogEntry computed properties
ci: add iOS build to CI pipeline

Architecture Rules

• Plugins must extend the core Plugin lifecycle classes
• No Android-specific imports in commonMain
• All state exposed as StateFlow (no LiveData)
• Compose UI uses Material3 exclusively
• Keep the public API surface minimal

Architecture Overview