mirror of
https://github.com/InsanusMokrassar/docs.git
synced 2024-11-08 09:24:00 +00:00
migrate kslog docs
This commit is contained in:
parent
089d0cebac
commit
e25c832543
3
docs/kslog/index.md
Normal file
3
docs/kslog/index.md
Normal file
@ -0,0 +1,3 @@
|
|||||||
|
# KSLog
|
||||||
|
|
||||||
|
[KSLog](https://github.com/InsanusMokrassar/kslog) is a simple multiplatform tool for native logging.
|
126
docs/kslog/logging.md
Normal file
126
docs/kslog/logging.md
Normal file
@ -0,0 +1,126 @@
|
|||||||
|
# Logging
|
||||||
|
|
||||||
|
> NOTE: **Message type notice**
|
||||||
|
> On this page all the messages will be just simple `String`, but you may pass any object as the message
|
||||||
|
|
||||||
|
As has been said in the [setup](setup.md) section, this library contains next levels of logging with their default representations on each platform:
|
||||||
|
|
||||||
|
| Weight (by order) | LogLevel name | JS | JVM Loggers | Android |
|
||||||
|
| -: | :- | :- | :- | :- |
|
||||||
|
| 0 | DEBUG | console.log | Level.FINEST | Log.d |
|
||||||
|
| 1 | VERBOSE | console.info | Level.FINE | Log.v |
|
||||||
|
| 2 | INFO | console.info | Level.INFO | Log.i |
|
||||||
|
| 3 | WARNING | console.warn | Level.WARNING | Log.w |
|
||||||
|
| 4 | ERROR | console.error | Level.SEVERE | Log.e |
|
||||||
|
| 5 | ASSERT | console.error | Level.SEVERE | Log.wtf |
|
||||||
|
|
||||||
|
Each of these levels have fullname and shortname shortcat extensions:
|
||||||
|
|
||||||
|
* `KSLog.debug`/`KSLog.d`/`KSLog.dS`
|
||||||
|
* `KSLog.verbose`/`KSLog.v`/`KSLog.vS`
|
||||||
|
* `KSLog.info`/`KSLog.i`/`KSLog.iS`
|
||||||
|
* `KSLog.warning`/`KSLog.w`/`KSLog.wS`
|
||||||
|
* `KSLog.error`/`KSLog.e`/`KSLog.eS`
|
||||||
|
* `KSLog.assert`/`KSLog.wtf`/`KSLog.wtfS`
|
||||||
|
|
||||||
|
And any of these shortcuts may accept one of several arguments combinations:
|
||||||
|
|
||||||
|
* Tag (Optional), Throwable (Optional), Message Builder (simple inline callback for lazy creating of log message). This type of arguments is duplicated with `S` suffix for `suspendable` messages creating, for example
|
||||||
|
* Message, Throwable (Optional)
|
||||||
|
* Tag, Message, Throwable (Optional)
|
||||||
|
|
||||||
|
So, when you want to log some expected exception, there are three common ways to do it:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val logger = KSLog.default
|
||||||
|
|
||||||
|
// with callback
|
||||||
|
logger.info(tag, throwable) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
|
||||||
|
// with suspendable callback
|
||||||
|
logger.infoS(tag, throwable) {
|
||||||
|
withContext(Dispatchers.Default) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Just with message
|
||||||
|
logger.info("Some your message for this event", throwable)
|
||||||
|
|
||||||
|
// With message and tag as strings
|
||||||
|
logger.info(tag, "Some your message for this event", throwable)
|
||||||
|
```
|
||||||
|
|
||||||
|
Of course, any of this calls can be shortenned:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val logger = KSLog.default
|
||||||
|
|
||||||
|
// with callback
|
||||||
|
logger.i(tag, throwable) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
|
||||||
|
// with suspendable callback
|
||||||
|
logger.iS(tag, throwable) {
|
||||||
|
withContext(Dispatchers.Default) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Just with message
|
||||||
|
logger.i("Some your message for this event", throwable)
|
||||||
|
|
||||||
|
// With message and tag as strings
|
||||||
|
logger.i(tag, "Some your message for this event", throwable)
|
||||||
|
```
|
||||||
|
|
||||||
|
There is special shortcat - for base `performLog`. In that case the only change is that you will require to pass the `LogLevel` more obviously:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val logger = KSLog.default
|
||||||
|
|
||||||
|
// with callback
|
||||||
|
logger.log(LogLevel.INFO, tag, throwable) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
|
||||||
|
// with suspendable callback
|
||||||
|
logger.logS(LogLevel.INFO, tag, throwable) {
|
||||||
|
withContext(Dispatchers.Default) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Just with message
|
||||||
|
logger.log(LogLevel.INFO, "Some your message for this event", throwable)
|
||||||
|
|
||||||
|
// With message and tag as strings
|
||||||
|
logger.log(LogLevel.INFO, tag, "Some your message for this event", throwable)
|
||||||
|
```
|
||||||
|
|
||||||
|
OR
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val logger = KSLog.default
|
||||||
|
|
||||||
|
// with callback
|
||||||
|
logger.l(LogLevel.INFO, tag, throwable) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
|
||||||
|
// with suspendable callback
|
||||||
|
logger.lS(LogLevel.INFO, tag, throwable) {
|
||||||
|
withContext(Dispatchers.Default) {
|
||||||
|
"Some your message for this event"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Just with message
|
||||||
|
logger.l(LogLevel.INFO, "Some your message for this event", throwable)
|
||||||
|
|
||||||
|
// With message and tag as strings
|
||||||
|
logger.l(LogLevel.INFO, tag, "Some your message for this event", throwable)
|
||||||
|
```
|
153
docs/kslog/setup.md
Normal file
153
docs/kslog/setup.md
Normal file
@ -0,0 +1,153 @@
|
|||||||
|
# Setup
|
||||||
|
|
||||||
|
## Dependency installation
|
||||||
|
|
||||||
|
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog/badge.svg)](https://maven-badges.herokuapp.com/maven-central/dev.inmo/kslog)
|
||||||
|
|
||||||
|
### Gradle (Groovy)
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
implementation "dev.inmo:kslog:$kslog_version"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Gradle (Kotlin Script)
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
implementation("dev.inmo:kslog:$kslog_version")
|
||||||
|
```
|
||||||
|
|
||||||
|
### Maven (pom)
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
KSLog.default = KSLog("defaultTag")
|
||||||
|
```
|
||||||
|
|
||||||
|
You may use custom `messageFormatter` in any of `KSLog` factory to customize output of `KSLog` logging. For example:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
* 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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
KSLog(
|
||||||
|
"yourTag"
|
||||||
|
Logger.getLogger("YourJavaLoggerName")
|
||||||
|
)
|
||||||
|
```
|
@ -29,6 +29,10 @@ nav:
|
|||||||
- Describing:
|
- Describing:
|
||||||
- 'krontab/describing/string-format.md'
|
- 'krontab/describing/string-format.md'
|
||||||
- 'krontab/describing/krontabscheduler.md'
|
- 'krontab/describing/krontabscheduler.md'
|
||||||
|
- 'KSLog':
|
||||||
|
- 'kslog/index.md'
|
||||||
|
- 'kslog/setup.md'
|
||||||
|
- 'kslog/logging.md'
|
||||||
|
|
||||||
use_directory_urls: false
|
use_directory_urls: false
|
||||||
|
|
||||||
|
Loading…
Reference in New Issue
Block a user