From 2ccb683b73bd6afd9eb867f103c6b1af7086c9f8 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 1 Jun 2023 19:28:30 +0100 Subject: [PATCH 1/4] Fix file placement --- Module.md => logging/Module.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename Module.md => logging/Module.md (100%) diff --git a/Module.md b/logging/Module.md similarity index 100% rename from Module.md rename to logging/Module.md From 400ea91c15e3a1ba242225d07cbc27cc09c31cad Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 1 Jun 2023 19:28:46 +0100 Subject: [PATCH 2/4] Extend readme with description of backends and contexts --- README.md | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 67 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 76ee62a18..f85fbb91d 100644 --- a/README.md +++ b/README.md @@ -18,12 +18,76 @@ 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. -## Gradle dependency -To use Spine Logging in your Gradle project: +## Logging backends + +The JVM implementation of the library uses Google Flogger as a backend, at least, for +the time being. Flogger, in turn, is also a logging facade, which means that it needs to +be configured with a backend which does actual logging operations. + +There are following logging Flogger backends available at the time of writing: + * `com.google.flogger:flogger-system-backend:$floggerVersion` — uses `java.util.logging`. + * `com.google.flogger:flogger-log4j-backend:$floggerVersion` — uses Log4. + * `com.google.flogger:flogger-log4j2-backend:$floggerVersion` — uses Log4j2. + * `com.google.flogger:flogger-slf4j-backend:$floggerVersion` — uses SLF4J (which is facade itself!). + +### Using `java.util.logging` as a backend +If you want to use `java.util.logging` in your project, you need to 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 the one which fixes the issues +with using `LogLevelMap` in the project. + +### Other backends +If you want a backend other than `java.util.logging`, you need to add dependencies that include +`rutimeOnly` dependency for a logging backend of choice. For example: + +```kotlin +dependencies { + implementation("io.spine:spine-logging:$version") + runtimeOnly("com.google.flogger:flogger-log4j2-backend:$floggerVersion") +} +``` + +If you need to use 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 is a set of attributes that are attached to all log records while +a context is installed. For example, you can attach a user ID to all log records for +the current request. + +Default implementation provides a no-op context, which does nothing. To use logging +context a `rutimeOnly` dependency for a context implementation should be added in addition +to the dependencies described above. + +If your project does not use gRPC, you need to use the following dependency: + +```kotlin +dependencies { + //... + rutimeOnly("io.spine:spine-logging-context:$version") +} +``` + +If your project does use gRPC, you need to add the following dependency instead: ```kotlin dependencies { - implementation("io.spine:spine-logging:${version}") + //... + rutimeOnly("com.google.flogger:flogger-grpc-context:$floggerVersion") } ``` From 828aab4cc80e9a8ac8f803662343579b469fdb53 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 1 Jun 2023 19:37:19 +0100 Subject: [PATCH 3/4] Improve text style --- README.md | 66 +++++++++++++++++++++++++++---------------------------- 1 file changed, 33 insertions(+), 33 deletions(-) diff --git a/README.md b/README.md index f85fbb91d..36a9cac6c 100644 --- a/README.md +++ b/README.md @@ -5,45 +5,47 @@ # 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. ## Logging backends -The JVM implementation of the library uses Google Flogger as a backend, at least, for -the time being. Flogger, in turn, is also a logging facade, which means that it needs to -be configured with a backend which does actual logging operations. +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: -There are following logging Flogger backends available at the time of writing: - * `com.google.flogger:flogger-system-backend:$floggerVersion` — uses `java.util.logging`. - * `com.google.flogger:flogger-log4j-backend:$floggerVersion` — uses Log4. - * `com.google.flogger:flogger-log4j2-backend:$floggerVersion` — uses Log4j2. - * `com.google.flogger:flogger-slf4j-backend:$floggerVersion` — uses SLF4J (which is facade itself!). +* `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: -### Using `java.util.logging` as a backend -If you want to use `java.util.logging` in your project, you need to 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 the one which fixes the issues -with using `LogLevelMap` in the project. +The second dependency replaces the default Flogger backend with a backend that resolves issues +with using LogLevelMap in the project. + +### Utilizing other backends -### Other backends -If you want a backend other than `java.util.logging`, you need to add dependencies that include -`rutimeOnly` dependency for a logging backend of choice. For example: +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 { @@ -52,8 +54,7 @@ dependencies { } ``` -If you need to use SLF4J as a backend, your dependencies should also include a backend for SLF4J. -For example: +For SLF4J as a backend, your dependencies should also include a backend for SLF4J. For example: ```kotlin dependencies { @@ -65,15 +66,14 @@ dependencies { ## Logging context -A logging context is a set of attributes that are attached to all log records while -a context is installed. For example, you can attach a user ID to all log records for +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. -Default implementation provides a no-op context, which does nothing. To use logging -context a `rutimeOnly` dependency for a context implementation should be added in addition -to the dependencies described above. +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, you need to use the following dependency: +If your project does not use gRPC, use the following dependency: ```kotlin dependencies { @@ -82,7 +82,7 @@ dependencies { } ``` -If your project does use gRPC, you need to add the following dependency instead: +If your project does use gRPC, add the following dependency: ```kotlin dependencies { From ab3ea608b8ca06950947fde531bbfee7f70f0d5a Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 1 Jun 2023 19:39:19 +0100 Subject: [PATCH 4/4] Bump version -> `2.0.0-SNAPSHOT.186` --- license-report.md | 36 ++++++++++++++++++------------------ pom.xml | 2 +- version.gradle.kts | 2 +- 3 files changed, 20 insertions(+), 20 deletions(-) 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/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")