diff --git a/README.md b/README.md index 76ee62a18..36a9cac6c 100644 --- a/README.md +++ b/README.md @@ -5,25 +5,89 @@ # Spine Logging -Spine Logging is a library for (potentially multi-platform) Kotlin and Java projects. -Only JMV implementation for Kotlin is currently provided, with JS implementation being -of priority. +Spine Logging is a versatile library designed for Kotlin and Java projects, with a potential +for multi-platform use. At present, we only provide a JVM implementation for Kotlin, +with a JavaScript implementation being our priority for future development. -The library is largely inspired by [Google Flogger][flogger] logging API, and introduction of -fluent logging API in [SLF4J in v2.0.0][fluent-slf4j]. +This library draws inspiration from the logging API of [Google Flogger][flogger], and +the introduction of a fluent logging API in [SLF4J v2.0.0][fluent-slf4j]. -## Experimental status +## Current status: Experimental -This library is in its early stages of development and is not yet stable. -Its API may change without notice in the near future. Therefore, you should use it with -caution in your projects until it is no longer considered experimental. +Please note that this library is still in the experimental phase of development and hence, +its API may undergo significant changes. As such, we advise using this library cautiously in +your projects until it has reached a stable release stage. -## Gradle dependency -To use Spine Logging in your Gradle project: +## Logging backends + +Our JVM implementation currently employs Google Flogger. +Since Flogger is a logging facade, it requires a backend to perform the actual logging operations. +At the time of writing, the following Flogger backends are available: + +* `com.google.flogger:flogger-system-backend:$floggerVersion` — utilizing `java.util.logging`. +* `com.google.flogger:flogger-log4j-backend:$floggerVersion` — utilizing Log4j. +* `com.google.flogger:flogger-log4j2-backend:$floggerVersion` — utilizing Log4j2. +* `com.google.flogger:flogger-slf4j-backend:$floggerVersion` — utilizing SLF4J (which is a facade itself!). + +### How to Use `java.util.logging` as a backend + +To use `java.util.logging` in your project, add the following dependency: + +```kotlin +dependencies { + implementation("io.spine:spine-logging:$version") + runtimeOnly("io.spine:spine-logging-backend:$version") +} +``` +The second dependency replaces the default Flogger backend with a backend that resolves issues +with using LogLevelMap in the project. + +### Utilizing other backends + +If you prefer a backend other than java.util.logging, add dependencies that include a `runtimeOnly` +dependency for your chosen logging backend. For instance: + +```kotlin +dependencies { + implementation("io.spine:spine-logging:$version") + runtimeOnly("com.google.flogger:flogger-log4j2-backend:$floggerVersion") +} +``` + +For SLF4J as a backend, your dependencies should also include a backend for SLF4J. For example: + +```kotlin +dependencies { + implementation("io.spine:spine-logging:$version") + runtimeOnly("com.google.flogger:flogger-slf4j-backend:$floggerVersion") + runtimeOnly("org.slf4j:slf4j-reload4j:$slf4jVersion") +} +``` + +## Logging context + +A logging context refers to a set of attributes that are attached to all log records while +a context is installed. For instance, you can attach a user ID to all log records for +the current request. + +The default implementation provides a no-op context. To use a logging context, a `runtimeOnly` +dependency for a context implementation should be added along with the above dependencies. + +If your project does not use gRPC, use the following dependency: + +```kotlin +dependencies { + //... + rutimeOnly("io.spine:spine-logging-context:$version") +} +``` + +If your project does use gRPC, add the following dependency: ```kotlin dependencies { - implementation("io.spine:spine-logging:${version}") + //... + rutimeOnly("com.google.flogger:flogger-grpc-context:$floggerVersion") } ``` diff --git a/license-report.md b/license-report.md index 9059c2b62..3f64ac365 100644 --- a/license-report.md +++ b/license-report.md @@ -1,6 +1,6 @@ -# Dependencies of `io.spine:spine-fixtures:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-fixtures:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.github.ajalt. **Name** : colormath. **Version** : 1.2.0. @@ -740,12 +740,12 @@ The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:35 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:31 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-jvm-log4j-backend-our-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-jvm-log4j-backend-our-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -1535,12 +1535,12 @@ This report was generated on **Thu Jun 01 16:38:35 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:36 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:32 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-jvm-our-backend-grpc-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-jvm-our-backend-grpc-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -2326,12 +2326,12 @@ This report was generated on **Thu Jun 01 16:38:36 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:36 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:32 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-jvm-our-backend-our-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-jvm-our-backend-our-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -3109,12 +3109,12 @@ This report was generated on **Thu Jun 01 16:38:36 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:33 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-jvm-slf4j-jdk14-backend-our-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-jvm-slf4j-jdk14-backend-our-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -3904,12 +3904,12 @@ This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:33 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-jvm-slf4j-reload4j-backend-our-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-jvm-slf4j-reload4j-backend-our-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -4703,12 +4703,12 @@ This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:34 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-logging:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-logging:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -5388,12 +5388,12 @@ This report was generated on **Thu Jun 01 16:38:37 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:38 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:34 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-logging-backend:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-logging-backend:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -6171,12 +6171,12 @@ This report was generated on **Thu Jun 01 16:38:38 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:38 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). +This report was generated on **Thu Jun 01 19:37:34 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). -# Dependencies of `io.spine:spine-logging-context:2.0.0-SNAPSHOT.185` +# Dependencies of `io.spine:spine-logging-context:2.0.0-SNAPSHOT.186` ## Runtime 1. **Group** : com.google.code.findbugs. **Name** : jsr305. **Version** : 3.0.2. @@ -6954,4 +6954,4 @@ This report was generated on **Thu Jun 01 16:38:38 WEST 2023** using [Gradle-Lic The dependencies distributed under several licenses, are used according their commercial-use-friendly license. -This report was generated on **Thu Jun 01 16:38:39 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file +This report was generated on **Thu Jun 01 19:37:35 WEST 2023** using [Gradle-License-Report plugin](https://github.com/jk1/Gradle-License-Report) by Evgeny Naumenko, licensed under [Apache 2.0 License](https://github.com/jk1/Gradle-License-Report/blob/master/LICENSE). \ No newline at end of file diff --git a/Module.md b/logging/Module.md similarity index 100% rename from Module.md rename to logging/Module.md diff --git a/pom.xml b/pom.xml index 58779e96e..ac532c0ed 100644 --- a/pom.xml +++ b/pom.xml @@ -10,7 +10,7 @@ all modules and does not describe the project structure per-subproject. --> io.spine spine-logging -2.0.0-SNAPSHOT.185 +2.0.0-SNAPSHOT.186 2015 diff --git a/version.gradle.kts b/version.gradle.kts index e6cd8a23d..36f9d9f75 100644 --- a/version.gradle.kts +++ b/version.gradle.kts @@ -24,4 +24,4 @@ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ -val versionToPublish: String by extra("2.0.0-SNAPSHOT.185") +val versionToPublish: String by extra("2.0.0-SNAPSHOT.186")