|
| 1 | +sklog - simple Kotlin logging |
| 2 | +============================= |
| 3 | + |
| 4 | +Kotlin (JVM) logging library for printing colorized text to the console, with an easy upgrade path to the |
| 5 | +popular [kotlin-logging library] |
| 6 | + |
| 7 | + |
| 8 | +Rationale |
| 9 | +--------- |
| 10 | +Logging is a necessary part of most projects, but setting it up can be a chore. |
| 11 | + |
| 12 | +Java has several popular logging frameworks, as well as the |
| 13 | +built-in [java.util.logging](https://docs.oracle.com/javase/8/docs/technotes/guides/logging/overview.html), but all come |
| 14 | +with their own [issues](https://logging.apache.org/log4j/2.x/security.html). |
| 15 | + |
| 16 | +For Kotlin, the [kotlin-logging library] has become relatively popular, but it's not a standalone logger. Instead, it |
| 17 | +acts as a wrapper around [SLF4J](https://www.slf4j.org/), which is itself a logging "facade" (i.e., frontend), meaning |
| 18 | +that it requires a separate backend/implementation to work. |
| 19 | + |
| 20 | +As a result, even if all you want to do is print log output to the console (`System.err`), you'll need to pull in three |
| 21 | +separate dependencies: kotlin-logging, SLF4J, and SLF4J's _[Simple](https://www.slf4j.org/manual.html#swapping)_ |
| 22 | +implementation. That can be a lot, especially for smaller projects with relatively simple logging needs. |
| 23 | + |
| 24 | +It can also be difficult to figure out how to configure these libraries, for example if you want to change the log level so that you actually see debug messages. |
| 25 | + |
| 26 | +This library exists to make it easy to start logging, without worrying about dependencies and complex configuration. |
| 27 | + |
| 28 | + |
| 29 | +Features |
| 30 | +-------- |
| 31 | + |
| 32 | +- No dependencies, other than the Kotlin language and the Java standard library |
| 33 | + - [The entire library is one file](sklog/src/main/kotlin/sklog/KotlinLogging.kt), which you can copy directly into |
| 34 | + your project! |
| 35 | +- Messages are printed to `System.err` |
| 36 | +- Output includes timestamp and the name of the class where the logger was declared |
| 37 | + - Possible to set custom logger names |
| 38 | +- Output colorized based on log level |
| 39 | + - But this can be disabled |
| 40 | +- Log level can be customized |
| 41 | +- No other customizations are available in this library |
| 42 | +- But it's **really easy to upgrade to a more full-featured solution**, the _[kotlin-logging library]_! (see below) |
| 43 | + |
| 44 | +Example & usage |
| 45 | +--------------- |
| 46 | + |
| 47 | + |
| 48 | + |
| 49 | +This screenshot was generated by the following program: |
| 50 | + |
| 51 | +```kotlin |
| 52 | +import sklog.KotlinLogging |
| 53 | +import sklog.LogLevel |
| 54 | + |
| 55 | +private val logger = KotlinLogging.logger {} |
| 56 | + |
| 57 | +fun main() { |
| 58 | + // The default log level is DEBUG, |
| 59 | + // but it can be set to TRACE globally or on a per-logger basis |
| 60 | + logger.logLevel = LogLevel.TRACE |
| 61 | + |
| 62 | + println("Welcome! This is a test run of sklog, the simple kotlin logging library.") |
| 63 | + println("Each of the following lines is logger output.") |
| 64 | + |
| 65 | + logger.trace { "Trace" } |
| 66 | + logger.debug { "Debug" } |
| 67 | + logger.info { "Info" } |
| 68 | + logger.warning("Warning") |
| 69 | + logger.error("Error") |
| 70 | +} |
| 71 | +``` |
| 72 | + |
| 73 | +Using this library |
| 74 | +------------------ |
| 75 | +This library is made available via [JitPack](https://jitpack.io/). Here's how you can add it to your project: |
| 76 | + |
| 77 | +### Gradle (`build.gradle.kts`) |
| 78 | + |
| 79 | +```kotlin |
| 80 | +repositories { |
| 81 | + maven { |
| 82 | + url = uri("https://jitpack.io") |
| 83 | + } |
| 84 | +} |
| 85 | + |
| 86 | +dependencies { |
| 87 | + implementation("com.github.nmalkin:sklog:0.0.1") |
| 88 | +} |
| 89 | +``` |
| 90 | + |
| 91 | +### Gradle (`build.gradle`) |
| 92 | + |
| 93 | +```gradle |
| 94 | +repositories { |
| 95 | + maven { |
| 96 | + url 'https://jitpack.io' |
| 97 | + } |
| 98 | +} |
| 99 | +
|
| 100 | +dependencies { |
| 101 | + implementation 'com.github.nmalkin:sklog:0.0.1' |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +### Maven |
| 106 | +```xml |
| 107 | +<repositories> |
| 108 | + <repository> |
| 109 | + <id>jitpack.io</id> |
| 110 | + <url>https://jitpack.io</url> |
| 111 | + </repository> |
| 112 | +</repositories> |
| 113 | + |
| 114 | +<dependency> |
| 115 | + <groupId>com.github.nmalkin</groupId> |
| 116 | + <artifactId>sklog</artifactId> |
| 117 | + <version>0.0.1</version> |
| 118 | +</dependency> |
| 119 | +``` |
| 120 | + |
| 121 | +Upgrade path |
| 122 | +------------ |
| 123 | +If you start using this library and realize you need more features, upgrading to the [kotlin-logging library] should be |
| 124 | +very easy! |
| 125 | +This library's API was based on kotlin-logging and designed to be compatible. In particular: |
| 126 | + |
| 127 | +- Loggers are declared the same way |
| 128 | + ```kotlin |
| 129 | + private val logger = KotlinLogging.logger {} |
| 130 | + ``` |
| 131 | +- Messages can be logged as lambdas (so they don't get evaluated if the log level is disabled) |
| 132 | + ```kotlin |
| 133 | + logger.debug { "Some $expensive message!" } |
| 134 | + ``` |
| 135 | + |
| 136 | +Because of this, upgrading to kotlin-logging might be as simple as swapping our your imports: |
| 137 | + |
| 138 | +```diff |
| 139 | +< import sklog.KotlinLogging |
| 140 | +--- |
| 141 | +> import mu.KotlinLogging |
| 142 | +``` |
| 143 | + |
| 144 | +[kotlin-logging library]: https://github.com/MicroUtils/kotlin-logging |
0 commit comments