Remove runtime SLF4J implementation (#476)

Remove the bundled SLF4J simple logger implementation, allowing users to
provide their own SLF4J implementation without conflicts.

- Remove slf4j-simple runtime dependency and related logging
configuration
- Test logging behavior for scripts and projects through a Logback-based
test
- Update docs to guide users on logging for each use case

Resolves #332.

### #332 copy

> The library ships with `simple-logger` instead of relying on the
consumer to provide SLF4J bindings. This was intentional to provide
out-of-the-box logging using the library from notebooks and scripts.
However, it's not obvious when using the library from projects.
> 
> ### Fix options
> 
> 1. Document it in the README and suggest excluding `simple-logger` in
the example `dependencies` snippet (unintuitive for projects)
> 2. Remove `simple-logger` and `logLevel` functionality (very
unintuitive for notebooks and scripts)

Author: gabrielfeo

README.md

@@ -165,6 +165,12 @@ from the same OpenAPI spec.
 
 ## Optional setup
 
+### Logging
+
+See [docs/Logging.md](docs/Logging.md) for how to configure logging in projects, scripts, and notebooks.
+
+### Code-based configuration
+
 Creating a custom [`Config`][8] allows you to change library settings via code instead of
 environment variables. It also lets you share resources between the library's `OkHttpClient` and
 your own. For example:

docs/Logging.md

@@ -0,0 +1,96 @@
+# Logging
+
+This library uses [SLF4J][1] but does not bundle an SLF4J implementation.
+
+- [Notebooks](#notebooks)
+- [Scripts](#scripts)
+    - [`simple-logger`](#simple-logger)
+- [Projects](#projects)
+    - [`simple-logger`](#simple-logger-1)
+
+## Notebooks
+
+1. Set `%logLevel <level>` in a code cell, e.g., `%logLevel debug`.
+
+Logs appear in the Kotlin Jupyter kernel logs:
+
+- In IntelliJ, view logs in the Kotlin Notebook logs tool window
+- In Jupyter and JupyterLab, logs appear in the shell that owns the Jupyter process
+
+![IntelliJ Kotlin Notebook logs tool window](media/IntelliJKernelLogs.png)
+
+⚠️ Older versions of the Kotlin Jupyter kernel had issues with logging. Kernel version `0.15.0-598` and higher are known to work. In IntelliJ, configure to use a later version than bundled. In pip and conda, update the kernel package.
+
+![IntelliJ Kotlin Jupyter kernel version configuration](media/IntelliJKernelSettings.png)
+
+## Scripts
+
+1. Add an SLF4J implementation (e.g., `slf4j-simple`, `logback-classic`, etc.)
+2. Set the log level for the package `com.gabrielfeo.develocity.api` using your chosen logging framework's configuration
+
+### `simple-logger`
+
+Adding `simple-logger` to your classpath is the easiest way to get logging in scripts. You can do this by adding the following line to your script:
+
+```kotlin
+@file:DependsOn("org.slf4j:slf4j-simple:2.0.17")
+```
+
+Then set the log level for `com.gabrielfeo.develocity.api` using system properties. For example:
+
+- from script code
+
+```kotlin
+@file:DependsOn("com.gabrielfeo:develocity-api-kotlin:2024.3.0")
+@file:DependsOn("org.slf4j:slf4j-simple:2.0.17")
+
+System.setProperty("org.slf4j.simpleLogger.log.com.gabrielfeo.develocity.api", "debug")
+
+// ...
+```
+
+- from the shebang line
+
+```kotlin
+#!/usr/bin/env kotlin -script -J-Dorg.slf4j.simpleLogger.log.com.gabrielfeo.develocity.api=debug
+
+@file:DependsOn("com.gabrielfeo:develocity-api-kotlin:2024.3.0")
+@file:DependsOn("org.slf4j:slf4j-simple:2.0.17")
+
+// ...
+```
+
+- from `JAVA_OPTS`
+
+```bash
+export JAVA_OPTS="-Dorg.slf4j.simpleLogger.log.com.gabrielfeo.develocity.api=debug"
+kotlin -script example-script.main.kts
+```
+
+## Projects
+
+1. Add an SLF4J implementation (e.g., `slf4j-simple`, `logback-classic`, etc.) to your classpath
+2. Set the log level for the package `com.gabrielfeo.develocity.api` using your chosen logging framework's configuration
+
+### `simple-logger`
+
+Adding `simple-logger` to your classpath is the easiest way to get logging in projects. You can do this by adding the following dependency to your build file:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("com.gabrielfeo:develocity-api-kotlin:2024.3.0")
+    runtimeOnly("org.slf4j:slf4j-simple:2.0.17")
+}
+```
+
+Then set the system property when running your application. If using the Gradle `run` task, it can be declared in your build:
+
+```kotlin
+tasks.named<JavaExec>("run") {
+    // ...
+    systemProperty("org.slf4j.simpleLogger.log.com.gabrielfeo.develocity.api", "debug")
+}
+```
+
+[0]: https://www.slf4j.org/

docs/media/IntelliJKernelLogs.png

@@ -11,6 +11,7 @@ retrofit = "3.0.0"
 kotlin-coroutines = "1.10.2"
 kotlin-binary-compatibility-validator = "0.18.1"
 slf4j = "2.0.17"
+logback = "1.5.18"
 guava = "33.4.8-jre"
 
 [libraries]
@@ -35,5 +36,6 @@ kotlin-stdlib = { module = "org.jetbrains.kotlin:kotlin-stdlib", version.ref = "
 dokka-plugin = { module = "org.jetbrains.dokka:dokka-gradle-plugin", version.ref = "dokka" }
 openapi-generator-plugin = { module = "org.openapitools:openapi-generator-gradle-plugin", version.ref = "openapi-generator" }
 slf4j-api = { module = "org.slf4j:slf4j-api", version.ref = "slf4j" }
-slf4j-simple = { module = "org.slf4j:slf4j-simple", version.ref = "slf4j" }
+logback-classic = { module = "ch.qos.logback:logback-classic", version.ref = "logback" }
+logback-core = { module = "ch.qos.logback:logback-core", version.ref = "logback" }
 guava = { module = "com.google.guava:guava", version.ref = "guava" }

docs/media/IntelliJKernelSettings.png

@@ -78,22 +78,20 @@ public final class com/gabrielfeo/develocity/api/BuildsApi$DefaultImpls {
 
 public final class com/gabrielfeo/develocity/api/Config {
 	public fun <init> ()V
-	public fun <init> (Ljava/lang/String;Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;)V
-	public synthetic fun <init> (Ljava/lang/String;Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
-	public final fun component1 ()Ljava/lang/String;
-	public final fun component2 ()Ljava/net/URI;
-	public final fun component3 ()Lkotlin/jvm/functions/Function0;
-	public final fun component4 ()Lokhttp3/OkHttpClient$Builder;
-	public final fun component5 ()Ljava/lang/Integer;
-	public final fun component6 ()J
-	public final fun component7 ()Lcom/gabrielfeo/develocity/api/Config$CacheConfig;
-	public final fun copy (Ljava/lang/String;Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;)Lcom/gabrielfeo/develocity/api/Config;
-	public static synthetic fun copy$default (Lcom/gabrielfeo/develocity/api/Config;Ljava/lang/String;Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;ILjava/lang/Object;)Lcom/gabrielfeo/develocity/api/Config;
+	public fun <init> (Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;)V
+	public synthetic fun <init> (Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
+	public final fun component1 ()Ljava/net/URI;
+	public final fun component2 ()Lkotlin/jvm/functions/Function0;
+	public final fun component3 ()Lokhttp3/OkHttpClient$Builder;
+	public final fun component4 ()Ljava/lang/Integer;
+	public final fun component5 ()J
+	public final fun component6 ()Lcom/gabrielfeo/develocity/api/Config$CacheConfig;
+	public final fun copy (Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;)Lcom/gabrielfeo/develocity/api/Config;
+	public static synthetic fun copy$default (Lcom/gabrielfeo/develocity/api/Config;Ljava/net/URI;Lkotlin/jvm/functions/Function0;Lokhttp3/OkHttpClient$Builder;Ljava/lang/Integer;JLcom/gabrielfeo/develocity/api/Config$CacheConfig;ILjava/lang/Object;)Lcom/gabrielfeo/develocity/api/Config;
 	public fun equals (Ljava/lang/Object;)Z
 	public final fun getAccessKey ()Lkotlin/jvm/functions/Function0;
 	public final fun getCacheConfig ()Lcom/gabrielfeo/develocity/api/Config$CacheConfig;
 	public final fun getClientBuilder ()Lokhttp3/OkHttpClient$Builder;
-	public final fun getLogLevel ()Ljava/lang/String;
 	public final fun getMaxConcurrentRequests ()Ljava/lang/Integer;
 	public final fun getReadTimeoutMillis ()J
 	public final fun getServer ()Ljava/net/URI;

gradle/libs.versions.toml

@@ -25,7 +25,6 @@ dependencies {
     implementation(libs.moshi.kotlin)
     api(libs.kotlin.coroutines)
     implementation(libs.slf4j.api)
-    runtimeOnly(libs.slf4j.simple)
     compileOnly(libs.kotlin.jupyter.api)
     testImplementation(libs.okhttp.mockwebserver)
     testImplementation(libs.okio.fakeFileSystem)
@@ -35,6 +34,8 @@ dependencies {
     integrationTestImplementation(libs.kotlin.coroutines.test)
     integrationTestImplementation(libs.guava)
     integrationTestImplementation(libs.kotlin.jupyter.testkit)
+    integrationTestImplementation(libs.logback.core)
+    integrationTestImplementation(libs.logback.classic)
 }
 
 val libraryPom = Action<MavenPom> {
@@ -111,7 +112,6 @@ tasks.withType<Test>().configureEach {
         "junit.jupiter.tempdir.cleanup.mode.default",
         System.getProperty("junit.jupiter.tempdir.cleanup.mode.default") ?: "always",
     )
-    environment("DEVELOCITY_API_LOG_LEVEL", "DEBUG")
     providers.environmentVariablesPrefixedBy("DEVELOCITY_API_").get().forEach { (name, value) ->
         inputs.property("${name}.hashCode", value.hashCode())
     }

library/api/library.api

@@ -0,0 +1,82 @@
+package com.gabrielfeo.develocity.api
+
+import ch.qos.logback.classic.Logger as LogbackLogger
+import ch.qos.logback.classic.spi.ILoggingEvent
+import ch.qos.logback.core.AppenderBase
+import ch.qos.logback.core.ConsoleAppender
+import ch.qos.logback.classic.encoder.PatternLayoutEncoder
+import com.gabrielfeo.develocity.api.internal.*
+import kotlinx.coroutines.test.runTest
+import org.junit.jupiter.api.io.TempDir
+import org.slf4j.Logger
+import org.slf4j.LoggerFactory
+import java.io.File
+import kotlin.test.*
+
+class LoggingIntegrationTest {
+
+    private class LogRecorder : AppenderBase<ILoggingEvent>() {
+        val logsByLoggerName = mutableListOf<Pair<String, String>>()
+        override fun append(eventObject: ILoggingEvent) {
+            with(eventObject) {
+                logsByLoggerName += (loggerName to formattedMessage)
+            }
+        }
+    }
+
+    @TempDir
+    lateinit var tempDir: File
+
+    private val recorder = LogRecorder()
+
+    private lateinit var api: DevelocityApi
+
+    @BeforeTest
+    fun setup() {
+        (LoggerFactory.getLogger(Logger.ROOT_LOGGER_NAME) as LogbackLogger).apply {
+            detachAndStopAllAppenders()
+            addAppender(recorder)
+            addAppender(ConsoleAppender<ILoggingEvent>().apply {
+                context = loggerContext
+                encoder = PatternLayoutEncoder().apply {
+                    context = loggerContext
+                    pattern = "%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"
+                    start()
+                }
+                start()
+            })
+        }
+        recorder.start()
+        env = RealEnv
+        api = DevelocityApi.newInstance(
+            config = Config(
+                cacheConfig = Config.CacheConfig(
+                    cacheEnabled = true,
+                    cacheDir = tempDir,
+                )
+            )
+        )
+    }
+
+    @AfterTest
+    fun tearDown() {
+        api.shutdown()
+    }
+
+    @Test
+    fun logsUnderLibraryPackage() = runTest {
+        api.buildsApi.getBuilds(since = 0, maxBuilds = 1)
+        with(recorder.logsByLoggerName) {
+            assertTrue(isNotEmpty())
+            assertTrue(any { (_, message) -> message.contains("cache dir", ignoreCase = true) })
+            assertTrue(any { (_, message) -> message.contains("cache miss", ignoreCase = true) })
+            assertTrue(any { (_, message) -> message.contains("get", ignoreCase = true) })
+            forEach { (loggerName, message) ->
+                assertTrue(
+                    loggerName.startsWith("com.gabrielfeo.develocity.api"),
+                    "Log from unexpected logger: '$loggerName' with message '$message'"
+                )
+            }
+        }
+    }
+}

library/build.gradle.kts

@@ -0,0 +1,11 @@
+<configuration>
+    <logger name="com.gabrielfeo.develocity" level="DEBUG"/>
+    <root level="INFO">
+        <appender-ref ref="CONSOLE"/>
+    </root>
+    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
+        <encoder>
+            <pattern>%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n</pattern>
+        </encoder>
+    </appender>
+</configuration>

library/src/integrationTest/kotlin/com/gabrielfeo/develocity/api/LoggingIntegrationTest.kt

@@ -15,33 +15,6 @@ import kotlin.time.Duration.Companion.days
 @Suppress("MemberVisibilityCanBePrivate", "unused")
 data class Config(
 
-    /**
-     * Changes minimum log level for library classes, including the HTTP
-     * client, **when using `slf4j-simple`** (bundled with the library). If
-     * replacing SLF4J bindings, this setting has no effect, and log level
-     * must be changed in the chosen logging framework.
-     *
-     * Default value, by order of precedence:
-     *
-     * - `DEVELOCITY_API_LOG_LEVEL` environment variable
-     * - `org.slf4j.simpleLogger.defaultLogLevel` system property
-     * - `"off"`
-     *
-     * SLF4J valid log levels and their usage by the library:
-     *
-     * - "off" (default, no logs)
-     * - "error"
-     * - "warn"
-     * - "info"
-     * - "debug" (logs HTTP traffic: URLs and status codes only)
-     * - "trace" (logs HTTP traffic: full request and response including body, excluding
-     *   authorization header)
-     */
-    val logLevel: String =
-        env["DEVELOCITY_API_LOG_LEVEL"]
-            ?: systemProperties.logLevel
-            ?: "off",
-
     /**
      * Provides the URL of a Develocity server to use in API requests. By default, uses environment
      * variable `DEVELOCITY_URL`. Must be a valid URL with no path segments (trailing slash OK) or