diff --git a/.idea/icon.png b/.idea/icon.png new file mode 100644 index 0000000..134a37c Binary files /dev/null and b/.idea/icon.png differ diff --git a/README.md b/README.md new file mode 100644 index 0000000..54451c5 --- /dev/null +++ b/README.md @@ -0,0 +1 @@ +KODEIN-LOG \ No newline at end of file diff --git a/doc/antora.yml b/doc/antora.yml new file mode 100644 index 0000000..f84f671 --- /dev/null +++ b/doc/antora.yml @@ -0,0 +1,12 @@ +name: kodein-log +title: Kodein-Log +version: '0.10' +display_version: '0.10.1' +nav: + - modules/ROOT/nav.adoc + - modules/core/nav.adoc +asciidoc: + attributes: + version: '0.10.1' + kotlin: '1.4.31' + jdk: '1.8' \ No newline at end of file diff --git a/doc/modules/ROOT/images/kodein-log-logo.svg b/doc/modules/ROOT/images/kodein-log-logo.svg new file mode 100644 index 0000000..7b9d9e9 --- /dev/null +++ b/doc/modules/ROOT/images/kodein-log-logo.svg @@ -0,0 +1 @@ +KODEINLogpainless logging \ No newline at end of file diff --git a/doc/modules/ROOT/nav.adoc b/doc/modules/ROOT/nav.adoc new file mode 100644 index 0000000..b8ebd07 --- /dev/null +++ b/doc/modules/ROOT/nav.adoc @@ -0,0 +1,2 @@ +* xref:index.adoc[Introduction] +* xref:getting-started.adoc[Quick start guide] diff --git a/doc/modules/ROOT/pages/getting-started.adoc b/doc/modules/ROOT/pages/getting-started.adoc new file mode 100644 index 0000000..05799c3 --- /dev/null +++ b/doc/modules/ROOT/pages/getting-started.adoc @@ -0,0 +1,79 @@ + += Getting started with Kodein-Log + +NOTE: This guide assumes a JVM target. + Kodein-Log works exactly the same on all targets that are supported by Kotlin (JVM, Android, JS, Native). + +== Install + +In your `build.gradle.kts` file, add the Maven Central repository: + +[source,kotlin] +---- +repositories { + mavenCentral() +} +---- + +Then add the dependency: + +[source,groovy,subs="attributes"] +---- +dependencies { + implementation 'org.kodein.log:kodein-log:{version}' +} +---- + +More detailed installation guide xref:core:install.adoc[here]. + +== Create and use a `Logger` + +Before being able to log anything, you need to create a `LoggerFactory`, +to define the format of your logs and on which frontend they should be sent. + +. create a `LoggerFactory` ++ +[source,kotlin] +---- +val loggerFactory = LoggerFactory.default // <1> +---- +<1> Initialize a `LoggerFactory` with the xref:core:usage.adoc#default-frontends[default] output format. + +. create a `Logger` ++ +[source,kotlin] +---- +class MyController { + private val logger = LoggerFactory.default.newLogger() // <1> +} +---- +<1> Initialize a `Logger` from a given `LoggerFactory`. ++ +[NOTE] +==== + +Thanks to the awesome Kotlin type system we can even go further, +without explicitly naming the Tag used for logging: + +[source,kotlin] +---- +class MyController(private val loggerFactory: LoggerFactory) { + private val logger = newLogger(loggerFactory) // <1> +} +---- +<1> Initialize a `Logger` from a given `LoggerFactory`, implicitly tagged with `MyController`. +==== + +. Use the logger ++ +[source,kotlin] +---- +logger.info { "Well done..." } +logger.warning { "...you have completed the Getting Started guide." } +---- ++ +NOTE: Logging levels available: `debug` / `info` / `warning` / `error`. + +More detailed on `Logger` xref:core:usage.adoc[initialization and usage]. + +If you want to know more about frontend implementation you can read xref:core:advanced.adoc[Working with custom frontends]. \ No newline at end of file diff --git a/doc/modules/ROOT/pages/index.adoc b/doc/modules/ROOT/pages/index.adoc new file mode 100644 index 0000000..0334bc1 --- /dev/null +++ b/doc/modules/ROOT/pages/index.adoc @@ -0,0 +1,42 @@ +image::kodein-log-logo.svg[KODEIN-LOG, 700] + +[.lead] +*_Kodein-Log_* is a lightweight Kotlin/Multiplatform logging library with a simple API, that works on JVM, Android, JavaScript, iOS, as well as for all Kotlin/Native targets. + +*_Kodein-Log_* allows you to: + +- easily setup logging in a Kotlin/Multiplatform +- simply log what you need on different level +- avoid carrying about platform specific frontends' implementations + +*_Kodein-Log_* is a good choice because: + +- it integrates nicely with all the Kotlin/Multiplatform targets +- it is small and simple to grasp with an easy and understandable API + +== Example + +[source, kotlin] +.simple example +---- +val loggerFactory = LoggerFactory(defaultLogFrontend) +val logger = newLogger(loggerFactory) + +logger.info { "Welcome to ..." } +logger.warning { "... the Kodein-Log documentation!" } +---- + +== Support + +- Drop by the https://kotlinlang.slack.com/messages/kodein/[Kodein Slack channel] +- https://stackoverflow.com/questions/tagged/kodein[Stackoverflow] with the tag #kodein + +== Contribute + +Contributions are very welcome and greatly appreciated! The great majority of pull requests are eventually merged. + +To contribute, simply fork https://github.com/Kodein-Framework/Kodein-Log[the project on Github], fix whatever is iching you, and submit a pull request! + +I am sure that this documentation contains typos, inaccuracies and languages error (English is not our mother tongue). +If you feel like enhancing this document, you can propose a pull request that modifies https://github.com/Kodein-Framework/Kodein-Log/tree/master/doc[the documentation documents]. +(Documentation is auto-generated from those). diff --git a/doc/modules/core/nav.adoc b/doc/modules/core/nav.adoc new file mode 100644 index 0000000..a48d46d --- /dev/null +++ b/doc/modules/core/nav.adoc @@ -0,0 +1,12 @@ +* xref:install.adoc[Install] +** xref:install.adoc#install-kmp[Kotlin/Multiplatform] +** xref:install.adoc#install-jvm[JVM & Android only] +** xref:install.adoc#install-js[JavaScript] +* xref:usage.adoc#logger[Create and use a `Logger`] +** xref:usage.adoc#tags[Tags] +** xref:usage.adoc#default-frontends[Default frontends] +** xref:usage.adoc#levels[Logging levels] +* xref:usage.adoc#logger-factory[Share the logger configuration] +* xref:usage.adoc#logmapper[Transform the outputs] +* xref:usage.adoc#logfilter[Filter the outputs] +* xref:advanced.adoc#custom-frontends[Working with custom frontends] \ No newline at end of file diff --git a/doc/modules/core/pages/advanced.adoc b/doc/modules/core/pages/advanced.adoc new file mode 100644 index 0000000..18514d5 --- /dev/null +++ b/doc/modules/core/pages/advanced.adoc @@ -0,0 +1,41 @@ += Advanced + +[[custom-frontends]] +== Working with custom frontends + +*_Kodein-Log_* is a facade for multiplatform developers that need an easy way to log without worrying about platform specific implementation. For that we provide xref:usage.adoc#default-frontends[[default frontends]] that are default output capacities, for each possible target of Kotlin/Multiplatform. + +However, we can think of a lot of use cases that might not covered by default frontends, ike saving the logs into a file, sending the logs to an upstream system, etc. + +If you want to use a custom implementation to handle your logs, you can create your own by using the interface `LogFrontend`. + +[source,kotlin] +.`logFrontend` +---- +public fun interface LogFrontend { + public fun getReceiverFor(tag: Logger.Tag): LogReceiver // <1> +} +---- +<1> You only have to override `getReceiverFor`. + +The `getReceiverFor` function will define what we should do of every logged entry. The rest depends on your use case. Here is an example of a frontend that will stack every log into a list: + +[source,kotlin] +.custom frontend +---- +class MemoryFrontend : LogFrontend { // <1> + val entries: MutableList> = ArrayList() // <2> + + override fun getReceiverFor(tag: Logger.Tag): LogReceiver = // <3> + LogReceiver { entry, message -> // <4> + entries += Triple(tag, entry, message) // <5> + } +} +---- +<1> implement `LogFrontend` +<2> create a mutable list that will carry the logs +<3> override `getReceiveFor` +<4> create a `LogReceiver` ... +<5> ... that populate the `entries` with each log received + +NOTE: We could use this example to periodically send our stack to an upstream server. \ No newline at end of file diff --git a/doc/modules/core/pages/install.adoc b/doc/modules/core/pages/install.adoc new file mode 100644 index 0000000..7498fbb --- /dev/null +++ b/doc/modules/core/pages/install.adoc @@ -0,0 +1,90 @@ +[[install]] += Install + +IMPORTANT: *_Kodein-Log_* uses the new gradle native dependency model. + Thus, we highly recommend to use Gradle 6 or higher. + +[[install-kmp]] +== Kotlin/Multiplatform + +NOTE: Kodein-Log supports the following targets: + +jvm, iosArm32, iosArm64, iosX64, JS, tvosarm64, tvosx64, watchosarm32, watchosarm64, watchosx86, linuxArm32Hfp, linuxMips32, linuxMipsel32, linuxX64, macosX64, mingwX64. + +In your `build.gradle.kts` file, add the Maven Central repository: + +[source,kotlin] +---- +repositories { + mavenCentral() +} +---- + +Then add the dependency: + +[source,kotlin,subs="attributes"] +---- +kotlin { + sourceSets { + commonMain { + dependencies { + implementation("org.kodein.log:kodein-log:{version}") + } + } + } +} +---- + +[TIP] +==== +If you are *NOT* using *Gradle 6+*, you should declare the use of the Gradle Metadata experimental feature + +[subs="attributes"] +.settings.gradle.kts +---- +enableFeaturePreview("GRADLE_METADATA") +---- +==== + +[[install-jvm]] +== JVM & Android + +On the JVM, *_Kodein-Log_* is compatible with both standard JVM and Android environments, with the same configuration. + +First, add the Maven Central repository: + +[source,kotlin] +---- +repositories { + mavenCentral() +} +---- + +Then add the dependency: + +[source,kotlin,subs="attributes"] +---- +dependencies { + implementation("org.kodein.log:kodein-log-jvm:{version}") +} +---- + +[[install-js]] +== JavaScript + +Add the Maven Central repository: + +[source,kotlin] +---- +repositories { + mavenCentral() +} +---- + +Then add the dependency: + +[source,kotlin,subs="attributes"] +---- +dependencies { + implementation("org.kodein.log:kodein-log-js:{version}") +} +---- \ No newline at end of file diff --git a/doc/modules/core/pages/usage.adoc b/doc/modules/core/pages/usage.adoc new file mode 100644 index 0000000..65776cd --- /dev/null +++ b/doc/modules/core/pages/usage.adoc @@ -0,0 +1,459 @@ += Kodein-Log usage + +*_Kodein-Log_* allows to easily log any message, with a simple API. +This guide is meant to walk you through all you need to know and use *_Kodein-Log_*. + +NOTE: *_Kodein-Log_* API is the same for all the Kotlin/Multiplatform targets. + However, under the hood each platform uses its own implementation (see xref:default-frontends[default frontends]). + +[[logger]] +== `Logger` + +Creating a logger is really simple. Before logging a message you need to express some parameters to help the logger to: + +- identify the logged entry, with a xref:tags[`Tag`], like `org.kodein.documentation.MyController` +- send the logged entry to the right output: console / file / platform specific logging system + +[source,kotlin] +.create a simple Logger +---- +Logger( + tag = Logger.Tag("org.kodein.log.documentation", "MyController"), // <1> + frontEnds = listOf(defaultLogFrontend) // <2> +). info { "Hey!" } +---- +<1> will identify any message logged with this `Logger` by prefixing them with this tag +<2> defines on which outputs the logged messages should be sent. + +.Output + INFO: 2021-04-01T12:20:37.648603 | org.kodein.log.documentation.MyController: Hey! + +[TIP] +==== +You can also use the companion function `Logger.from` to create a logger. +[source,kotlin] +---- +Logger.from(defaultLogFrontend) // <1> +---- +<1> Type receiver is inferred at compile time and automatically passed as `tag` argument to a new `Logger` instance. +==== + +NOTE: You can share the configuration of your application's loggers by using a xref:logger-factory[factory]. + +[[tags]] +=== Tags + +As define above we know that a `Tag` helps us identify our logged message. +A `Tag` is always shaped in two parts, a _package_ and a _class name_. + +There are two ways of creating a `Tag`, you can either create it manually using String arguments, or a given `KClass`. + +[source,kotlin] +.Create a `Tag` manually +---- +Tag(pckg = "org.kodein.log.documentation", name = "MyController") +---- + +[source,kotlin] +.Create a `Tag` from a class +---- +Tag(MyController::class) +---- + +[TIP] +==== +The `Tag` can be inferred by Kotlin type system when using one of the extension functions: + +- `Logger.from(vararg frontends: LogFrontend)` +- `LoggerFactory.newLogger()` +- `T.newLogger(factory: LoggerFactory)` + +More details in xref:logger-factory[factory] section. +==== + +[[default-frontends]] +=== Default frontends + +*_Kodein-Log_* is lightweight because it is just a facade that we plug on top of logging systems. +_Frontends_ represent the implementations of the logging systems that *_Kodein-Log_* relies on to output your logs, depending on the platform your application is running on. + +The main reason behind *_Kodein-Log_* existence is that we want to provide an easy way of logging for Kotlin/Multiplatform developers, without worrying about the platform specifics. Therefore, *_Kodein-Log_* has the notion of default frontends, that uses the _expect/actual_ mechanism, sending the logs to the right output, depending on the actual platform. Those default implementations are accessible with the property `defaultLogFrontend`. + +[source,kotlin] +.use default log frontend +---- +Logger.from(defaultLogFrontend) // <1> +---- +<1> Use the specific frontend defined by *_Kodein-Log_* + +Here is a table that expose which implementation are used, by +targeted platform. + +[cols="1*,1*^.^"] +|=== +|Targeted platform ^.^|Frontend implementation + +|JVM +|http://www.slf4j.org[SLF4J] + +|Android +^.^|https://developer.android.com/reference/android/util/Log[Android Log] + +a|Apple + +- iOS +- macOS +- watchOS +- tvOS + +^.^|https://developer.apple.com/documentation/oslog[Apple OSLog] + +a|Other Kotlin/Native targets + +- Linux +- Windows + +^.^|System standard output + +|Kotlin/JS +^.^|https://developer.mozilla.org/en-US/docs/Web/API/Console/log[JavaScript console log] +|=== + +TIP: Remember that you can define your own xref:advanced.adoc#custom-frontends[frontends]. + +[[severity]] +=== Severity + +As for any logging library *_Kodein-Log_* provide different severities to log messages: + +- `logger.debug("Hey!")` -> `DEBUG: