prepare 5.10.0 release

CONTRIBUTING.md

@@ -56,13 +56,15 @@ The project in the `benchmarks` subdirectory uses [JMH](https://openjdk.java.net
 
 ### Logging
 
-Currently the SDK uses SLF4J for all log output. Here some things to keep in mind for good logging behavior:
+The SDK uses a LaunchDarkly logging facade, [`com.launchdarkly.logging`](https://github.com/launchdarkly/java-logging). By default, this facade sends output to SLF4J.
+
+Here some things to keep in mind for good logging behavior:
 
 1. Stick to the standardized logger name scheme defined in `Loggers.java`, preferably for all log output, but definitely for all log output above `DEBUG` level. Logger names can be useful for filtering log output, so it is desirable for users to be able to reference a clear, stable logger name like `com.launchdarkly.sdk.server.LDClient.Events` rather than a class name like `com.launchdarkly.sdk.server.EventSummarizer` which is an implementation detail. The text of a log message should be distinctive enough that we can easily find which class generated the message.
 
-2. Use parameterized messages (`Logger.MAIN.info("The value is {}", someValue)`) rather than string concatenation (`Logger.MAIN.info("The value is " + someValue)`). This avoids the overhead of string concatenation if the logger is not enabled for that level. If computing the value is an expensive operation, and it is _only_ relevant for logging, consider implementing that computation via a custom `toString()` method on some wrapper type so that it will be done lazily only if the log level is enabled.
+2. Use parameterized messages (`logger.info("The value is {}", someValue)`) rather than string concatenation (`logger.info("The value is " + someValue)`). This avoids the overhead of string concatenation if the logger is not enabled for that level. If computing the value is an expensive operation, and it is _only_ relevant for logging, consider implementing that computation via a custom `toString()` method on some wrapper type so that it will be done lazily only if the log level is enabled.
 
-3. Exception stacktraces should only be logged at debug level. For instance: `Logger.MAIN.warn("An error happened: {}", ex.toString()); Logger.MAIN.debug(ex.toString(), ex)`. Also, consider whether the stacktrace would be at all meaningful in this particular context; for instance, in a `try` block around a network I/O operation, the stacktrace would only tell us (a) some internal location in Java standard libraries and (b) the location in our own code where we tried to do the operation; (a) is very unlikely to tell us anything that the exception's type and message doesn't already tell us, and (b) could be more clearly communicated by just writing a specific log message.
+3. There is a standard pattern for logging exceptions, using the `com.launchdarkly.logging.LogValues` helpers. First, log the basic description of the exception at whatever level is appropriate (`WARN` or `ERROR`): `logger.warn("An error happened: {}", LogValues.exceptionSummary(ex))`. Then, log a stack at debug level: `logger.debug(LogValues.exceptionTrace(ex))`. The `exceptionTrace` helper is lazily evaluated so that the stacktrace will only be computed if debug logging is actually enabled. However, consider whether the stacktrace would be at all meaningful in this particular context; for instance, in a `try` block around a network I/O operation, the stacktrace would only tell us (a) some internal location in Java standard libraries and (b) the location in our own code where we tried to do the operation; (a) is very unlikely to tell us anything that the exception's type and message doesn't already tell us, and (b) could be more clearly communicated by just writing a specific log message.
 
 ### Code coverage
 

README.md

@@ -27,7 +27,13 @@ Refer to the [SDK reference guide](https://docs.launchdarkly.com/sdk/server-side
 
 ## Logging
 
-The LaunchDarkly SDK uses [SLF4J](https://www.slf4j.org/). All loggers are namespaced under `com.launchdarkly`. For an example configuration check out the [hello-java](https://github.com/launchdarkly/hello-java) project.
+By default, the LaunchDarkly SDK uses [SLF4J](https://www.slf4j.org/). SLF4J has its own configuration mechanisms for determining where output will go, and filtering by level and/or logger name.
+
+The SDK can also be configured to use other adapters from the [com.launchdarkly.logging](https://github.com/launchdarkly/java-logging) facade instead of SLF4J. See `LoggingConfigurationBuilder`. This allows the logging behavior to be completely determined by the application, rather than by external SLF4J configuration.
+
+For an example of using the default SLF4J behavior with a simple console logging configuration, check out the [`slf4j-logging` branch](https://github.com/launchdarkly/hello-java/tree/slf4j-logging) of the [`hello-java`](https://github.com/launchdarkly/hello-java) project. The [main branch](https://github.com/launchdarkly/hello-java) of `hello-java` uses console logging that is programmatically configured without SLF4J.
+
+All loggers are namespaced under `com.launchdarkly`, if you are using name-based filtering.
 
 Be aware of two considerations when enabling the DEBUG log level:
 1. Debug-level logs can be very verbose. It is not recommended that you turn on debug logging in high-volume environments.

benchmarks/src/jmh/java/com/launchdarkly/sdk/server/LDClientEvaluationBenchmarks.java

@@ -54,6 +54,7 @@ public BenchmarkInputs() {
         .dataStore(specificDataStore(dataStore))
         .events(Components.noEvents())
         .dataSource(Components.externalUpdatesOnly())
+        .logging(Components.noLogging())
         .build();
       client = new LDClient(SDK_KEY, config);
 

build.gradle

@@ -73,6 +73,7 @@ ext.versions = [
     "guava": "30.1-jre",
     "jackson": "2.11.2", 
     "launchdarklyJavaSdkCommon": "1.3.0",
+    "launchdarklyLogging": "1.1.0",
     "okhttp": "4.9.3", // specify this for the SDK build instead of relying on the transitive dependency from okhttp-eventsource
     "okhttpEventsource": "2.6.2",
     "slf4j": "1.7.21",
@@ -131,6 +132,7 @@ libraries.internal = [
 // also as package exports (i.e. it provides them if a newer version is not available
 // from an import).
 libraries.external = [
+    "com.launchdarkly:launchdarkly-logging:${versions.launchdarklyLogging}",
     "org.slf4j:slf4j-api:${versions.slf4j}"
 ]
 
@@ -322,6 +324,14 @@ javadoc {
     // Use test classpath so Javadoc won't complain about java-sdk-common classes that internally
     // reference stuff we don't use directly, like Jackson
     classpath = sourceSets.test.compileClasspath
+
+    // The following should allow hyperlinks to com.launchdarkly.logging classes to go to
+    // the correct external URLs
+    if (options instanceof StandardJavadocDocletOptions) {
+        (options as StandardJavadocDocletOptions).links(
+            "https://javadoc.io/doc/com.launchdarkly/launchdarkly-logging/${versions.launchdarklyLogging}"
+        )
+    }
 }
 
 // Force the Javadoc build to fail if there are any Javadoc warnings. See: https://discuss.gradle.org/t/javadoc-fail-on-warning/18141/3

contract-tests/service/src/main/java/sdktest/SdkClientEntity.java

@@ -42,7 +42,7 @@ public SdkClientEntity(TestService owner, CreateInstanceParams params) {
     this.logger = LoggerFactory.getLogger(params.tag);
     logger.info("Starting SDK client");
 
-    LDConfig config = buildSdkConfig(params.configuration);
+    LDConfig config = buildSdkConfig(params.configuration, params.tag);
     this.client = new LDClient(params.configuration.credential, config);
     if (!client.isInitialized() && !params.configuration.initCanFail) {
       throw new RuntimeException("client initialization failed or timed out");
@@ -184,9 +184,11 @@ public void close() {
     logger.info("Test ended");
   }
 
-  private LDConfig buildSdkConfig(SdkConfigParams params) {
+  private LDConfig buildSdkConfig(SdkConfigParams params, String tag) {
     LDConfig.Builder builder = new LDConfig.Builder();
 
+    builder.logging(Components.logging().baseLoggerName(tag + ".sdk"));
+
     if (params.startWaitTimeMs != null) {
       builder.startWait(Duration.ofMillis(params.startWaitTimeMs.longValue()));
     }

src/main/java/com/launchdarkly/sdk/server/BigSegmentStoreWrapper.java

@@ -5,6 +5,7 @@
 import com.google.common.cache.CacheBuilder;
 import com.google.common.cache.CacheLoader;
 import com.google.common.cache.LoadingCache;
+import com.launchdarkly.logging.LDLogger;
 import com.launchdarkly.sdk.EvaluationReason.BigSegmentsStatus;
 import com.launchdarkly.sdk.server.interfaces.BigSegmentStore;
 import com.launchdarkly.sdk.server.interfaces.BigSegmentStoreStatusProvider.Status;
@@ -15,7 +16,6 @@
 
 import org.apache.commons.codec.digest.DigestUtils;
 import org.checkerframework.checker.nullness.qual.NonNull;
-import org.slf4j.Logger;
 
 import java.io.Closeable;
 import java.io.IOException;
@@ -27,23 +27,23 @@
 import java.util.concurrent.TimeUnit;
 
 class BigSegmentStoreWrapper implements Closeable {
-  private static final Logger logger = Loggers.BIG_SEGMENTS;
-
   private final BigSegmentStore store;
   private final Duration staleAfter;
   private final ScheduledFuture<?> pollFuture;
   private final LoadingCache<String, Membership> cache;
   private final EventBroadcasterImpl<StatusListener, Status> statusProvider;
-
+  private final LDLogger logger;
   private final Object statusLock = new Object();
   private Status lastStatus;
 
   BigSegmentStoreWrapper(BigSegmentsConfiguration config,
                          EventBroadcasterImpl<StatusListener, Status> statusProvider,
-                         ScheduledExecutorService sharedExecutor) {
+                         ScheduledExecutorService sharedExecutor,
+                         LDLogger logger) {
     this.store = config.getStore();
     this.staleAfter = config.getStaleAfter();
     this.statusProvider = statusProvider;
+    this.logger = logger;
 
     CacheLoader<String, Membership> loader = new CacheLoader<String, Membership>() {
       @Override

src/main/java/com/launchdarkly/sdk/server/ClientContextImpl.java

@@ -1,6 +1,7 @@
 package com.launchdarkly.sdk.server;
 
-import com.launchdarkly.sdk.server.interfaces.ApplicationInfo;
+import com.launchdarkly.logging.LDLogger;
+import com.launchdarkly.logging.Logs;
 import com.launchdarkly.sdk.server.interfaces.BasicConfiguration;
 import com.launchdarkly.sdk.server.interfaces.ClientContext;
 import com.launchdarkly.sdk.server.interfaces.HttpConfiguration;
@@ -52,11 +53,35 @@ private ClientContextImpl(
       ScheduledExecutorService sharedExecutor,
       DiagnosticAccumulator diagnosticAccumulator
   ) {
-    this.basicConfiguration = new BasicConfiguration(sdkKey, configuration.offline, configuration.threadPriority, configuration.applicationInfo, configuration.serviceEndpoints);
+    // There is some temporarily over-elaborate logic here because the component factory interfaces can't
+    // be updated to make the dependencies more sensible till the next major version.
+    BasicConfiguration tempBasic = new BasicConfiguration(sdkKey, configuration.offline, configuration.threadPriority,
+        configuration.applicationInfo, configuration.serviceEndpoints, LDLogger.none());
+    this.loggingConfiguration = configuration.loggingConfigFactory.createLoggingConfiguration(tempBasic);
+    LDLogger baseLogger = LDLogger.withAdapter(
+        loggingConfiguration.getLogAdapter() == null ? Logs.none() : loggingConfiguration.getLogAdapter(),
+        loggingConfiguration.getBaseLoggerName() == null ? Loggers.BASE_LOGGER_NAME :
+          loggingConfiguration.getBaseLoggerName()
+        );
+
+    this.basicConfiguration = new BasicConfiguration(
+        sdkKey,
+        configuration.offline,
+        configuration.threadPriority,
+        configuration.applicationInfo,
+        configuration.serviceEndpoints,
+        baseLogger
+        );
 
     this.httpConfiguration = configuration.httpConfigFactory.createHttpConfiguration(basicConfiguration);
-    this.loggingConfiguration = configuration.loggingConfigFactory.createLoggingConfiguration(basicConfiguration);
-
+
+
+    if (this.httpConfiguration.getProxy() != null) {
+      baseLogger.info("Using proxy: {} {} authentication.",
+          this.httpConfiguration.getProxy(),
+          this.httpConfiguration.getProxyAuthentication() == null ? "without" : "with");
+    }
+
     this.sharedExecutor = sharedExecutor;
 
     if (!configuration.diagnosticOptOut && diagnosticAccumulator != null) {

src/main/java/com/launchdarkly/sdk/server/Components.java

@@ -2,6 +2,8 @@
 
 import static com.launchdarkly.sdk.server.ComponentsImpl.NULL_EVENT_PROCESSOR_FACTORY;
 
+import com.launchdarkly.logging.LDLogAdapter;
+import com.launchdarkly.logging.Logs;
 import com.launchdarkly.sdk.server.ComponentsImpl.EventProcessorBuilderImpl;
 import com.launchdarkly.sdk.server.ComponentsImpl.HttpBasicAuthentication;
 import com.launchdarkly.sdk.server.ComponentsImpl.HttpConfigurationBuilderImpl;
@@ -316,14 +318,63 @@ public static HttpAuthentication httpBasicAuthentication(String username, String
    *         .build();
    * </code></pre>
    * 
-   * @return a factory object
+   * @return a configuration builder
    * @since 5.0.0
    * @see LDConfig.Builder#logging(com.launchdarkly.sdk.server.interfaces.LoggingConfigurationFactory)
    */
   public static LoggingConfigurationBuilder logging() {
     return new LoggingConfigurationBuilderImpl();
   }
 
+  /**
+   * Returns a configuration builder for the SDK's logging configuration, specifying the
+   * implementation of logging to use.
+   * <p>
+   * This is a shortcut for <code>Components.logging().adapter(logAdapter)</code>. The
+   * <a href="https://github.com/launchdarkly/java-logging"><code>com.launchdarkly.logging</code></a>
+   * API defines the {@link LDLogAdapter} interface to specify where log output should be sent. By default,
+   * it is set to {@link com.launchdarkly.logging.LDSLF4J#adapter()}, meaning that output will be sent to
+   * <a href="https://www.slf4j.org/">SLF4J</a> and controlled by the SLF4J configuration. You may use
+   * the {@link com.launchdarkly.logging.Logs} factory methods, or a custom implementation, to handle log
+   * output differently. For instance, you may specify {@link com.launchdarkly.logging.Logs#basic()} for
+   * simple console output, or {@link com.launchdarkly.logging.Logs#toJavaUtilLogging()} to use the
+   * <code>java.util.logging</code> framework.
+   * <p>
+   * Passing this to {@link LDConfig.Builder#logging(com.launchdarkly.sdk.server.interfaces.LoggingConfigurationFactory)},
+   * after setting any desired properties on the builder, applies this configuration to the SDK.
+   * <pre><code>
+   *     LDConfig config = new LDConfig.Builder()
+   *         .logging(
+   *              Components.logging(Logs.basic())
+   *         )
+   *         .build();
+   * </code></pre>
+   * 
+   * @param logAdapter the log adapter
+   * @return a configuration builder
+   * @since 5.10.0
+   * @see LDConfig.Builder#logging(com.launchdarkly.sdk.server.interfaces.LoggingConfigurationFactory)
+   * @see LoggingConfigurationBuilder#adapter(LDLogAdapter)
+   */
+  public static LoggingConfigurationBuilder logging(LDLogAdapter logAdapter) {
+    return logging().adapter(logAdapter);
+  }
+
+  /**
+   * Returns a configuration builder that turns off SDK logging.
+   * <p>
+   * Passing this to {@link LDConfig.Builder#logging(com.launchdarkly.sdk.server.interfaces.LoggingConfigurationFactory)}
+   * applies this configuration to the SDK.
+   * <p>
+   * It is equivalent to <code>Components.logging(com.launchdarkly.logging.Logs.none())</code>.
+   * 
+   * @return a configuration builder
+   * @since 5.10.0
+   */
+  public static LoggingConfigurationBuilder noLogging() {
+    return logging().adapter(Logs.none());
+  }
+
   /**
    * Returns a configuration builder for the SDK's application metadata.
    * <p>