Configuration
A Context manages loggers and Providers. Each Provider defines its output destination, log level, and formatter.
Create a logger
Create loggers through ColotokLoggerContext and retain the context for application shutdown. In 1.0.0, ColotokLogger constructors are internal and loggers no longer expose shutdown() or forceShutdown(). See Migrating to 1.0.
getLogger() returns a logger backed by the Context's Providers. ConsoleProvider writes to the platform console.
On Android, the default ConsoleProvider() does not write to Logcat. From your Android source set, supply the debug-mode decision explicitly when debug output is wanted:
Output is enabled only when isOutputEnabled && (isEnabledForRelease || detectDebugModeFn()) is true. The defaults are true, false, and { false }, respectively, so the default result is no output. Colotok does not infer BuildConfig.DEBUG.
Print log
Text Logging
Select a method matching the log level:
Use atInfo to write several messages at the same level:
Structured Logging
Colotok prints structured logs using kotlinx.serialization. The Provider worker serializes the submitted message object. Use immutable message types to keep its values consistent from submission through output. See field masking for sensitive fields.
Implement the log structure. The serialization plugin generates the serializer used by the logger.
Configure DetailStructureFormatter to serialize the message as JSON.
Write the structured message:
Shutdown and Flushing Logs
Since Colotok processes logs asynchronously, stop application logging and explicitly shut down the logger context before the application exits.
Configure Context metrics with withMetrics(), then register Providers with addProvider(). Registration selects each Provider's effective collector from the Context and its metricsSpec. withMetrics() sets the Context collector used for subsequent registrations.
The following lifecycle contract applies to 1.0.0. A logger uses its context's providers; stopping the context stops those destinations for all loggers that share them. shallowCopy() also shares Provider instances, so stopping a copied context affects the original context's shared destinations. Copies do not have independent provider lifetimes.
Normal Shutdown
shutdown() gracefully closes each configured provider and suspends until its queued logs have been processed, its provider-specific buffer has been flushed, and its resources have been closed. Providers are closed and joined sequentially in registration order. Stop application logging before calling shutdown. Cancellation of the calling coroutine interrupts the wait and can leave later Providers open; use a completion callback with forceShutdown() when graceful shutdown cannot continue.
Force Shutdown
Use forceShutdown() to stop accepting records and request cancellation of the provider workers. This call returns without waiting for worker termination or resource release on every target, including JVM, Android, JS/Node, and Native.
Queued records may be lost, and an in-progress operation is cancelled cooperatively. Forced shutdown does not start a final flush. The close hook runs after the operation's cleanup; a custom operation that ignores cancellation can delay resource release. Returning from this method is not permission to terminate the process if logging cleanup is still required.
To continue application shutdown after cleanup, use the completion overload:
applicationScope is an application-owned CoroutineScope; the reporting and finishing functions are application-specific. The callback is a suspend lambda and is dispatched in the supplied scope's execution context. It is scheduled after all targeted workers and their resource cleanup have finished, including when the context has no providers or the providers have already stopped. Resource release is performed once; each completion registration can be notified once. If a close hook fails, the callback reports that failure; do not assume every external resource was successfully released. Report shutdown failures through a destination outside the stopped logger context.
Result.success(Unit)means cancellation and cleanup finished without a recorded provider failure. It does not guarantee delivery of queued records.Result.failure(cause)reports a recorded processing, flush, or close failure. The context reports the first failure it observes after all targeted providers have finished.The callback is not part of provider termination. Callback exceptions belong to the supplied scope's normal exception handling and do not change the provider result.
The scope must remain active until notification completes. Cancelling it can suppress or interrupt the callback, but does not undo the shutdown request. Process termination can also prevent notification. No callback ordering across separate requests is guaranteed.
Supply an application scope with appropriate exception handling if the callback can fail; its exception is not thrown synchronously from the forceShutdown() call.
For a single Provider, provider.forceShutdown { result -> ... } uses the Provider's own scope. provider.forceShutdown(applicationScope) { result -> ... } selects an external notification scope. Cancelling the Provider's entire scope can suppress the default notification.
From a suspend function, provider.join() is another completion boundary: after forced shutdown it waits for the worker and cleanup, then throws ProviderClosedException to report forced termination. If a provider failure was recorded, that original failure is thrown instead. Calling context.shutdown() after forcing its providers similarly waits and reports their forced termination or failure; it does not convert forced termination into graceful success.
Manual Flush
If you only want to ensure that records accepted before a point are processed without shutting down the context, flush individual providers while they are open:
Provider.close() starts graceful closure but does not wait. Provider.join() starts closure when necessary and suspends until worker termination and resource release. flush() is only valid while open: after graceful or forced closure starts it throws ProviderClosedException, unless a recorded provider failure takes precedence. Lifecycle hooks must not wait for their own provider's join() or flush(); these self-waits are rejected with IllegalStateException.
Event snapshots and delivery
Choose the logging call according to the enqueue behavior you need:
atInfoAsync { print(...) }provides a suspending block with non-blockingprint()calls. Eachprint()usesProvider.write(), including forAsyncProvider.Message calls such as
infoAsync(message)andatAsync(level, message)wait for channel capacity when the destination is anAsyncProvider.
The event timestamp, thread, caller where supported, attributes, and MDC are snapshotted at the logging call. Delayed formatting and remote publication keep that original event time. Mutating the original maps afterwards does not change output, and every provider receives the same event snapshot for that call. JavaScript currently leaves caller empty because no portable JS call-site implementation is provided.
On JS/Node, MDC follows Node AsyncLocalStorage resources. Root operations, nested scope restoration, and native async-chain propagation are supported. Kotlin coroutine siblings are not guaranteed to have isolated MDC mutation because a coroutine Job is not always a separate Node async resource. Logging-call snapshots remain isolated.
On Kotlin/Native, MDC is thread-local. Basic operations and logging-call snapshots are supported on the current thread; automatic propagation or isolation across coroutine thread switches is not guaranteed.
For an AsyncProvider, bufferSize is a publish threshold in 1..4096. Failed batches are retained up to min(bufferSize * 4, 4096) records. When that capacity is exhausted, the newest incoming record is dropped, preserving the older records for retry. If a remote destination accepts part of a batch before the provider reports failure, retrying the retained batch can produce duplicates; integrations should tolerate duplicates. Bounded queues, retention limits, and forced shutdown can lose records; at-least-once delivery is not guaranteed.
At full retention capacity, the Provider keeps the buffered batch and drops new records. Retry that batch with flush() or graceful shutdown; incoming records do not trigger publication while the buffer is full. A flush failure is reported to the caller and puts the Provider in its failed state. Subsequent lifecycle calls report the original failure.
There is no time-based automatic flush. A low-volume buffer stays pending until the next publish threshold, an explicit flush(), or graceful shutdown.
The flush(timeout) timeout includes waiting to enqueue the marker and waiting for its processing; the default is one second. A timeout does not undo an already enqueued marker or confirm remote delivery.
A structured record holds a reference to its message object. The worker serializes that object when it formats the record; event metadata is captured separately at the logging call. Use immutable message types to keep message values consistent through output.
An automatic publish failure is recorded and can be retried by a later publish attempt. A failure from an explicit flush() is propagated and moves the provider to its failed terminal state; join() reports the same original failure.