Log

abstract class Log(source)

An abstraction for dynamic logging.

Various Log implementations can be installed into Root whereby Logger logs get directed. By default, the only Log instance available at Root is AbortHandler. If no other Log implementations are installed, then no logging occurs (this is by design).

Application developers are able to tailor logging to their needs, such as a debug build Log implementation and a release Log implementation for crash reporting.

Library authors also have the means to add granular logging to their codebase by use of Logger, while not sacrificing performance, leaving their end-users in complete control over what logs are generated (if any). See Logger.domain.

e.g. (Using SysLog from kmp-log:sys)

val logger = Log.Logger.of(tag = "Example")
logger.i { "This will not be logged" }
Log.Root.install(SysLog.Debug)
logger.i { "This WILL be logged" }
Log.Root.uninstall(SysLog.UID)

Inheritors

AbortHandler

Constructors

Log

protected constructor(uid: String, min: Log.Level)

Instantiate a new Log instance.

protected constructor(uid: String, min: Log.Level, max: Log.Level)

Instantiate a new Log instance.

Types

AbortHandler

object AbortHandler : Log

A Log instance that, when installed (the default configuration), will handle finalization of Level.Fatal logs by aborting the program. This instance will always be the last Root.installed instance, giving a chance for all other installed Log instances to capture the log. If no other Log instances logged the Level.Fatal log, printStackTrace will be used to output the error before aborting.

Level

enum Level : Enum<Log.Level>

Logger

class Logger

Logs things to installed Log implementation(s) at Root.

Root

object Root

The root location for which all Log instances are installed. By default, only AbortHandler is available; Log implementations must be installed for logging to occur.

Properties

max

@JvmField

val max: Log.Level

The maximum log level for this Log instance. Logs with a level greater than this will be ignored.

min

@JvmField

val min: Log.Level

The minimum log level for this Log instance. Logs with a level less than this will be ignored.

uid

@JvmField

val uid: String

A unique identifier for this Log instance, such as a package name or a hash of a file path. Root.install uses this value to inhibit multiple instances from being installed.

Functions

isLoggable

protected open fun isLoggable(level: Log.Level, domain: String?, tag: String): Boolean

Helper for implementations to filter by a logger's domain and/or tag.

log

protected abstract fun log(level: Log.Level, domain: String?, tag: String, msg: String?, t: Throwable?): Boolean

Log something.

onInstall

protected open fun onInstall()

Helper for implementations to delay initialization of things to time of Root.install. This is called just prior to making the Log available to logging functions, and is done so while holding a lock. Implementations should be fast, non-blocking, and not throw exception.

onUninstall

protected open fun onUninstall()

Helper for implementations to clean up any resources at time of Root.uninstall. This is called after the Log has been removed from the list of available Log, and is done so while holding a lock. Implementations should be fast, non-blocking, and not throw exception.

Log

See also

Inheritors

Constructors

Types

Properties

Functions