Skip to content

# KSLog

It is simple and easy-to-use tool for logging on the most popular platforms in Kotlin Multiplatform:

By default, KSLog is using built-in tools for logging on each supported platform:

- `java.util.logging.Logger` for `JVM`
- `android.util.Log` for `Android`
- `Console` for `JS`

But you always may create your logger and customize as you wish:

    KSLog.default = KSLog { level: LogLevel, tag: String?, message: Any, throwable: Throwable? ->
        // do your logging
    }

This library also supports native targets in experimental mode. By default, all native targets will use simple printing in the console

## How to use

### Fast-travel

Just use some boring extensions like:

    KSLog.i("Some message")
    // OR
    KSLog.i("Some tag", "Some message")
    // OR
    KSLog.i("Some tag", "Some message", IllegalArgumentException("So, that is exception :)"))
    // OR
    KSLog.i("Some optional tag", Exception("Optional")) { "Lazy inited message" }
    // OR
    KSLog.iS("Some optional tag", Exception("Optional")) { "Lazy inited message for suspendable calculation of text" }
    // OR EVEN
    KSLog.l(LogLevel.INFO, "Some tag", "Some message", IllegalArgumentException("So, that is exception :)"))
    // OR
    KSLog.l(LogLevel.INFO, "Some optional tag", IllegalArgumentException("So, that is exception :)")) { "And lazily inited message" }

### A little bit deeper

There are several important “terms” in context of this library:

- Default logger (available via `KSLog.default` or simply `KSLog`)
- Local logger (can be created via `KSLog` functions and passed anywhere as `KSLog`)
- Logging shortcuts like `KSLog.i`/`KSLog.info`
- Built-in extension `Any.logger` which allow you to create logger binded to the default with the tag based on the class of receiver
  - Be careful with the receivers: if you will use some extension like `apply`, the receiver will be different with your class inside of that `apply`

Every logging extension (like `KSLog.i`) have its analog with lazy inited message text and the same one with suffix `S` (like `KSLog.iS`) for the suspendable message calculation.

Default logger can be created by passing `defaultTag` and one of variants log level filters: set or minimal loggable level. In `JVM` you also may setup any logger as base logger for default realizations of `KSLog`. Besides, you may use your own callback (on any target platform) as output of logging:

    val logger = KSLog { logLevel, optionalTag, message, optionalThrowable ->
        println("[$logLevel] $optionalTag - $message: $optionalThrowable.stackTraceToString()")
    }

In the example above we will take the `logger` which will just print incoming data as common output.

## Installation

### Gradle

    implementation "dev.inmo:kslog:$kslog_version"

### Maven

    <dependency>
      <groupId>dev.inmo</groupId>
      <artifactId>kslog</artifactId>
      <version>${kslog_version}</version>
    </dependency>