A Kotlin Multiplatform logging runtime for structured events, contextual metadata, and pluggable local or remote destinations.

Documentation · Maven Central · Releases · Issues

Colotok lets shared Kotlin code create one log event and route it to any combination of console, file, stream, Grafana Loki, AWS CloudWatch, or your own provider. It includes structured logging, MDC, configurable formatting, file rotation, runtime metrics, buffered remote delivery, and explicit provider shutdown.

• Route once, deliver anywhere. Attach multiple providers without coupling application log calls to a specific destination.
• Keep events structured. Log serializable event types or text with attributes, and capture MDC together with each event.
• Use the same runtime across supported targets. The core, coroutine, and Loki modules cover JVM, Android, JS/Node, iOS Arm64, iOS Simulator Arm64, and macOS Arm64.
• Control delivery explicitly. Providers define buffering, failure reporting, flushing, and graceful or forced shutdown instead of hiding delivery behind process termination.
• Meet existing JVM code where it is. Optional SLF4J 1.7 and 2.x bindings route existing SLF4J calls through Colotok.

Colotok is a particularly good fit when a KMP application needs more than platform-console output: structured context, file rotation, a remote log destination, or a reusable provider pipeline.

Add Colotok 1.0.0 to your project:

Add the root artifact to commonMain. Gradle module metadata selects the appropriate target variant; do not add target-suffixed coordinates such as -jvm, -android, or -js manually.

kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("io.github.milkcocoa0902:colotok:1.0.0")
        }
    }
}

Create a context, attach a provider, and get a logger:

import com.milkcocoa.info.colotok.core.logger.ColotokLoggerContext
import com.milkcocoa.info.colotok.core.provider.builtin.console.ConsoleProvider
import com.milkcocoa.info.colotok.core.provider.builtin.console.ConsoleProviderConfig

val context = ColotokLoggerContext()
    .addProvider(ConsoleProvider(ConsoleProviderConfig()))

val logger = context.getLogger("checkout")

logger.info("Order accepted", mapOf("orderId" to "A-42"))
logger.warn("Inventory is low")

When the application stops, close the context so accepted records are processed and provider resources are released:

suspend fun stopLogging() {
    context.shutdown()
}

[!IMPORTANT] Android console output is disabled by default. Configure detectDebugModeFn, or explicitly opt into release output, from the Android source set. Colotok does not infer your application's BuildConfig.DEBUG. See the configuration guide.

Enable the Kotlin serialization compiler plugin when your log event types use @Serializable. Use the same version as the Kotlin Gradle plugin in your project.

Colotok 1.0.0 is built with Kotlin/KGP 2.4.21. Use Kotlin 2.4.21 for JS/Node: Kotlin 2.3.21 cannot read the JS KLIB ABI produced by 2.4.21. See compiler compatibility for the tested compiler and platform combinations.

plugins {
    kotlin("plugin.serialization") version "2.4.21"
}

Pass immutable event types: the Provider worker serializes the submitted message object. Structured formatters preserve JSON objects, arrays, primitive values, and nulls. See field masking for sensitive fields.

Define an event type and select a structured formatter:

import com.milkcocoa.info.colotok.core.formatter.builtin.structure.DetailStructureFormatter
import com.milkcocoa.info.colotok.core.formatter.details.LogStructure
import kotlinx.serialization.Serializable

@Serializable
data class CheckoutEvent(
    val orderId: String,
    val total: Long,
) : LogStructure

val logger = ColotokLoggerContext()
    .addProvider(
        ConsoleProvider(
            ConsoleProviderConfig().apply {
                formatter = DetailStructureFormatter
            },
        ),
    )
    .getLogger("checkout")

logger.info(
    CheckoutEvent(orderId = "A-42", total = 4200),
    mapOf("requestId" to "req-7f3"),
)

The serialization runtime required by Colotok's public API is already included. A separate runtime dependency is normally unnecessary.

Providers are independent destinations. A single context can write locally and remotely without changing application log calls.

import com.milkcocoa.info.colotok.core.formatter.builtin.structure.DetailStructureFormatter
import com.milkcocoa.info.colotok.core.logger.ColotokLoggerContext
import com.milkcocoa.info.colotok.core.provider.builtin.console.ConsoleProvider
import com.milkcocoa.info.colotok.core.provider.builtin.console.ConsoleProviderConfig
import com.milkcocoa.info.colotok.core.provider.loki.LokiProvider

val context = ColotokLoggerContext()
    .addProvider(ConsoleProvider(ConsoleProviderConfig()))
    .addProvider(
        LokiProvider {
            host = "http://localhost:3100"
            logStream = mapOf("app" to "checkout", "environment" to "local")
            formatter = DetailStructureFormatter
        },
    )

val logger = context.getLogger("checkout")
logger.info("Order accepted", mapOf("orderId" to "A-42"))

Add the Loki integration beside the core dependency:

commonMain.dependencies {
    implementation("io.github.milkcocoa0902:colotok-loki:1.0.0")
}

See official integrations for Loki, CloudWatch, coroutines, and SLF4J setup.

Apple x86 targets (iosX64 and macosX64) are not supported in 1.0.0. Check this table before adopting Colotok for a target not explicitly listed above.

Kotlin logging projects solve different layers of the problem. A facade supplies a logging API and delegates delivery to another backend. A logging runtime owns event processing and output components such as providers, writers, appenders, or sinks.

The comparison reflects each project's documentation as of 2026-08-22. Target support and integrations vary by module and release.

• Built-in ConsoleProvider, FileProvider, and StreamProvider.
• Custom Provider for local destinations and buffered AsyncProvider for remote destinations.
• Plain, simple, and detailed text formatters.
• Simple and detailed structured formatters, plus custom formatters.
• Size-based and duration-based file rotation.

• Per-call attributes and MDC snapshots.
• JVM coroutine MDC scopes, Node AsyncLocalStorage integration, and thread-local Native behavior.
• Accepted-enqueue, rejection/error, and async-buffer metrics.
• Inherited, explicit, internal-logging, and composite metrics collectors.

Platform context propagation is not identical. On JS/Node, Kotlin coroutine siblings are not guaranteed to isolate MDC mutation. On Kotlin/Native, MDC is thread-local and does not automatically follow coroutine thread switches. Every log event still captures its own metadata snapshot at the logging call.

Providers use the following delivery and shutdown behavior:

• Provider.write() is non-blocking and best-effort. With the default overflow policy, a full channel rejects the newest record and preserves the accepted FIFO prefix.
• AsyncProvider.writeAsync() suspends for channel capacity and rethrows a failed channel cause. Normal closure rejects the record through metrics without throwing. Scoped atInfoAsync { print(...) } calls use non-blocking write(); use message-based async calls when capacity waiting is required.
• Failed remote batches are retained within a bounded buffer. Retrying a retained batch can duplicate records if a destination accepted only part of the failed request; delivery is not exactly once, and bounded buffers can still reject or drop records under pressure.
• Batches are sent at threshold multiples, at the retention limit, on explicit flush(), and during graceful shutdown. There is no timer-based automatic flush; low-volume records can remain buffered until the application flushes or shuts down.
• A failed batch at the retention limit requires explicit flush or graceful shutdown to retry; subsequent incoming records are dropped without another automatic publish attempt.
• flush() waits for records accepted before its marker while the provider is open. Its timeout includes enqueueing the marker and waiting for its processing; the default is one second.
• ColotokLoggerContext.shutdown() gracefully drains and closes providers. In 1.0.0, forceShutdown() requests cancellation and may lose queued records. It returns without waiting for worker termination or resource release.

context.forceShutdown(callbackScope, onComplete) invokes the callback after all targeted Providers stop and run their cleanup hooks. Result.success(Unit) indicates that no Provider failure was recorded; forced shutdown can discard queued records. Keep the notification scope active until the callback completes. Callback exceptions use that scope's exception handling. Create loggers through context.getLogger() and stop logging through the context. See the 1.0 migration guide for changes from the published 0.5.0 API, including Logger constructors, lifecycle methods, and IProvider implementations.

Read the configuration guide and metrics reference before relying on buffering or failure metrics in production.

• Introduction and installation
• Logger configuration and lifecycle
• Provider configuration
• Formatter configuration
• Metrics
• Official integrations
• Create a custom provider
• Create a custom formatter

Questions, bug reports, and focused pull requests are welcome through GitHub Issues. When reporting runtime behavior, include the Colotok version, target, provider configuration, and a minimal reproduction where possible.

Colotok is available under the Apache License 2.0.