Skip to content

# Setup

## Dependency installation

### Gradle (Groovy)

    implementation "dev.inmo:kslog:$kslog_version"

### Gradle (Kotlin Script)

    implementation("dev.inmo:kslog:$kslog_version")

### Maven (pom)

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

## Setup in code

The main point in setup in your code is to setup default logger:

    KSLog.default = KSLog("defaultTag")

You may use custom `messageFormatter` in any of `KSLog` factory to customize output of `KSLog` logging. For example:

    KSLog(
      "loggingWithCustomFormat",
      messageFormatter = { level, tag, message, throwable ->
        println("[$level] $tag - $message: $throwable")
      }
    )

Additionally you may use one of several different settings:

- `minLoggingLevel` - minimal logging level for the log which will be logged. The order of log level is next:
  - TRACE
  - DEBUG
  - VERBOSE
  - INFO
  - WARNING
  - ERROR
  - ASSERT
- `levels` - and iterable with the levels which should be logged
- `firstLevel`,`secondLevel`,`otherLevels` - as `levels`, but `vararg` :)

In case you are passing `minLoggingLevel`, the level and more important levels will be passed to logs. For example, when you are settings up your logger as in next snippet:

    val logger = KSLog(
        "exampleTag",
        minLoggingLevel = LogLevel.INFO
    )

The next levels will be logged with `logger`:

- `INFO`
- `WARNING`
- `ERROR`
- `ASSERT`

## Special loggers

### CallbackKSLog

It is logger which will call incoming `performLogCallback` on each logging. This logger can be create simply with one callback:

    KSLog { level, tag, message, throwable ->
      println("[$level] $tag - $message: $throwable")
    }

### TagLogger

It is simple value class which can be used for zero-cost usage of some tag and calling for `KSLog.default`. For example, if you will create tag logger with next code:

    val logger = TagLogger("tagLoggerTag")

The `logger` will call `KSLog.default` with the tag `tagLoggerTag` on each calling of logging.

### FilterKSLog

This pretty simple logger will call its `fallbackLogger` only in cases when incoming `messageFilter` will return true for logging:

    val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
    val filtered = baseLogger.filtered { _, t, _ ->
        t == "base"
    }

In the example above `baseLogger` will perform logs in two ways: when it has been called directly or when we call log performing with the tag `"base"` or `null`. Besides, you can see there extension `filtered` which allow to create `FilterKSLog` logger with simple lambda.

### TypedKSLog

This logger accepts map of types with the target loggers. You may build this logger with the special simple DSL:

    val baseLogger = KSLog("base") // log everything with the tag `base` if not set other
    val typed = buildTypedLogger {
      on<Int>(baseLogger) // log all ints to the baseLogger
      on<Float> { _, _, message, _ ->// log all floats to the passed logger
        println(message.toString()) // just print all floats
      }
      default { level, tag, message, throwable ->
        KSLog.performLog(level, tag, message, throwable)
      }
    }

### Automatical loggers

There are two things which can be useful in your code: `logger` and `logTag` extensions. `logTag` is the autocalculated by your object classname tag. `logger` extension can be used with applying to any object like in the next snippet:

    class SomeClass {
      init {
        logger.i("inited")
      }
    }

The code above will trigger calling of logging in `KSLog.default` with level `LogLevel.INFO` using tag `SomeClass` and message `"inited"`. As you could have guessed, `logger` is using `TagLogger` with `logTag` underhood and the most expensive operation here is automatical calculation of `logTag`.

- Extension `logger`

## JVM specific setup

For JVM you may setup additionally use java loggers as the second parameter of `KSLog` factory. For example:

    KSLog(
      "yourTag"
      Logger.getLogger("YourJavaLoggerName")
    )