Explain wire/frame logging logUserData (#2125)

* Explain wire/frame logging `logUserData`
Motivation:
The current debugging examples include a minimal explanation of the
`logUserData` feature of `enableWireLogging` and `enableFrameLogging`
which could be expanded to clarify the use.
Modifications:
Additional explanation of `logUserData` by provided by defining a
`LOG_USER_DATA` constant with JavaDoc
Result:
Improved examples.

* review feedback

servicetalk-examples/grpc/debugging/src/main/java/io/servicetalk/examples/grpc/debugging/DebuggingClient.java

@@ -43,7 +43,9 @@
  * </ol>
  * <p>The wire and frame logging features require that you configure a logger with an appropriate log level. For this
  * example {@code log4j2.xml} is used by both the client and server and configures the
- * ({@code servicetalk-examples-wire-logger} logger at {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level.
+ * {@code servicetalk-examples-wire-logger} and {@code servicetalk-examples-h2-frame-logger} loggers at
+ * {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level. Wire logging is configured to include logging of all
+ * user data contained in the payload, see {@link #LOG_USER_DATA}.
  *
  * <p>When configured correctly the output should be similar to the following:
  * <pre>
@@ -109,6 +111,20 @@ public final class DebuggingClient {
         // AsyncContext.disable();
     }
 
+    /**
+     * Logging of protocol user data is disabled to reduce output but can be enabled by using
+     * {@code Boolean.TRUE::booleanValue}. Logging user data may expose sensitive content contained in the headers or
+     * payload body. Care and consideration should be taken before enabling this feature on production systems.
+     *
+     * <p>If {@link Boolean#TRUE} then all user data in the headers and payload bodies will be logged in addition to
+     * network events.
+     * <p>If {@link Boolean#FALSE} then only network events will be logged, but user data contents will be omitted.
+     *
+     * <p>This implementation uses a constant function to enable or disable logging of user data, your implementation
+     * could selectively choose at runtime to log user data based upon application state or context.</p>
+     */
+    static final BooleanSupplier LOG_USER_DATA = Boolean.FALSE::booleanValue;
+
     public static void main(String[] args) throws Exception {
         try (BlockingGreeterClient client = GrpcClients.forAddress("localhost", 8080)
                 .initializeHttp(builder -> builder
@@ -126,18 +142,16 @@ public static void main(String[] args) throws Exception {
                          * Dumping of protocol bodies is disabled to reduce output but can be enabled by using
                          * {@code Boolean.TRUE::booleanValue}.
                          */
-                        .enableWireLogging("servicetalk-examples-wire-logger", TRACE, Boolean.FALSE::booleanValue)
+                        .enableWireLogging("servicetalk-examples-wire-logger", TRACE, LOG_USER_DATA)
 
                         /*
                          * 4. Enables detailed logging of HTTP2 frames, but not frame contents.
                          * Be sure to also enable the logger in your logging config file,
                          * {@code log4j2.xml} for this example.
-                         * Dumping of protocol bodies is disabled to reduce output but can be enabled by using
-                         * {@code Boolean.TRUE::booleanValue}.
                          */
                         .protocols(HttpProtocolConfigs.h2()
                                 .enableFrameLogging(
-                                        "servicetalk-examples-h2-frame-logger", TRACE, Boolean.FALSE::booleanValue)
+                                        "servicetalk-examples-h2-frame-logger", TRACE, LOG_USER_DATA)
                                 .build()))
                 .buildBlocking(new ClientFactory())) {
             HelloReply reply = client.sayHello(HelloRequest.newBuilder().setName("World").build());

servicetalk-examples/grpc/debugging/src/main/java/io/servicetalk/examples/grpc/debugging/DebuggingServer.java

@@ -37,7 +37,9 @@
  * </ol>
  * <p>The wire and frame logging features require that you configure a logger with an appropriate log level. For this
  * example {@code log4j2.xml} is used by both the client and server and configures the
- * ({@code servicetalk-examples-wire-logger} logger at {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level.
+ * {@code servicetalk-examples-wire-logger} and {@code servicetalk-examples-h2-frame-logger} loggers at
+ * {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level. Wire logging is configured to include logging of all
+ * user data contained in the payload, see {@link #LOG_USER_DATA}.
  *
  * <p>When configured correctly the output should be similar to the following:
  * <pre>
@@ -107,6 +109,20 @@ public final class DebuggingServer {
         // AsyncContext.disable();
     }
 
+    /**
+     * Logging of protocol user data is disabled to reduce output but can be enabled by using
+     * {@code Boolean.TRUE::booleanValue}. Logging user data may expose sensitive content contained in the headers or
+     * payload body. Care and consideration should be taken before enabling this feature on production systems.
+     *
+     * <p>If {@link Boolean#TRUE} then all user data in the headers and payload bodies will be logged in addition to
+     * network events.
+     * <p>If {@link Boolean#FALSE} then only network events will be logged, but user data contents will be omitted.
+     *
+     * <p>This implementation uses a constant function to enable or disable logging of user data, your implementation
+     * could selectively choose at runtime to log user data based upon application state or context.</p>
+     */
+    static final BooleanSupplier LOG_USER_DATA = Boolean.FALSE::booleanValue;
+
     public static void main(String[] args) throws Exception {
         GrpcServers.forPort(8080)
                 .initializeHttp(builder -> {
@@ -125,18 +141,16 @@ public static void main(String[] args) throws Exception {
                              * Dumping of protocol bodies is disabled to reduce output but can be enabled by using
                              * {@code Boolean.TRUE::booleanValue}.
                              */
-                            .enableWireLogging("servicetalk-examples-wire-logger", TRACE, Boolean.FALSE::booleanValue)
+                            .enableWireLogging("servicetalk-examples-wire-logger", TRACE, LOG_USER_DATA)
 
                             /*
                              * 4. Enables detailed logging of HTTP2 frames, but not frame contents.
                              * Be sure to also enable the logger in your logging config file,
                              * {@code log4j2.xml} for this example.
-                             * Dumping of protocol bodies is disabled to reduce output but can be enabled by using
-                             * {@code Boolean.TRUE::booleanValue}.
                              */
                             .protocols(HttpProtocolConfigs.h2()
                                     .enableFrameLogging(
-                                            "servicetalk-examples-h2-frame-logger", TRACE, Boolean.FALSE::booleanValue)
+                                            "servicetalk-examples-h2-frame-logger", TRACE, LOG_USER_DATA)
                                     .build());
                 })
                 .listenAndAwait((BlockingGreeterService) (ctx, request) ->

servicetalk-examples/http/debugging/build.gradle

@@ -18,6 +18,7 @@ apply plugin: "java"
 apply from: "../../gradle/idea.gradle"
 
 dependencies {
+  implementation project(":servicetalk-annotations")
   implementation project(":servicetalk-http-netty")
 
   runtimeOnly "org.apache.logging.log4j:log4j-slf4j-impl:$log4jVersion"

servicetalk-examples/http/debugging/src/main/java/io/servicetalk/examples/http/debugging/DebuggingExampleClient.java

@@ -40,7 +40,9 @@
  * </ol>
  * <p>The wire and frame logging features require that you configure a logger with an appropriate log level. For this
  * example {@code log4j2.xml} is used by both the client and server and configures the
- * ({@code servicetalk-examples-wire-logger} logger at {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level.
+ * {@code servicetalk-examples-wire-logger} and {@code servicetalk-examples-h2-frame-logger} loggers at
+ * {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level. Wire logging is configured to include logging of all
+ * user data contained in the payload, see {@link #LOG_USER_DATA}.
  *
  * <p>When configured correctly the output should be similar to the following:
  * <pre>
@@ -141,6 +143,19 @@ public final class DebuggingExampleClient {
         // AsyncContext.disable();
     }
 
+    /**
+     * Log all protocol user data. Logging user data may expose sensitive content contained in the headers or payload
+     * body. Care and consideration should be taken before enabling this feature on production systems.
+     *
+     * <p>If {@link Boolean#TRUE} then all user data in the headers and payload bodies will be logged in addition to
+     * network events.
+     * <p>If {@link Boolean#FALSE} then only network events will be logged, but user data contents will be omitted.
+     *
+     * <p>This implementation uses a constant function to enable or disable logging of user data, your implementation
+     * could selectively choose at runtime to log user data based upon application state or context.</p>
+     */
+    static final BooleanSupplier LOG_USER_DATA = Boolean.TRUE::booleanValue;
+
     public static void main(String... args) throws Exception {
         try (HttpClient client = HttpClients.forSingleAddress("localhost", 8080)
                 /*
@@ -154,14 +169,14 @@ public static void main(String... args) throws Exception {
                  * 3. Enables detailed logging of I/O and I/O states.
                  * Be sure to also enable the logger in your logging config file (log4j2.xml for this example).
                  */
-                .enableWireLogging("servicetalk-examples-wire-logger", TRACE, Boolean.TRUE::booleanValue)
+                .enableWireLogging("servicetalk-examples-wire-logger", TRACE, LOG_USER_DATA)
 
                 /*
                  * 4. Enables detailed logging of HTTP2 frames.
                  * Be sure to also enable the logger in your logging config file (log4j2.xml for this example).
                  */
                 .protocols(HttpProtocolConfigs.h2()
-                        .enableFrameLogging("servicetalk-examples-h2-frame-logger", TRACE, Boolean.TRUE::booleanValue)
+                        .enableFrameLogging("servicetalk-examples-h2-frame-logger", TRACE, LOG_USER_DATA)
                         .build())
                 .build()) {
             client.request(client.post("/sayHello").payloadBody("George", textSerializerUtf8()))

servicetalk-examples/http/debugging/src/main/java/io/servicetalk/examples/http/debugging/DebuggingExampleServer.java

@@ -40,7 +40,9 @@
  * </ol>
  * <p>The wire and frame logging features require that you configure a logger with an appropriate log level. For this
  * example {@code log4j2.xml} is used by both the client and server and configures the
- * ({@code servicetalk-examples-wire-logger} logger at {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level.
+ * {@code servicetalk-examples-wire-logger} and {@code servicetalk-examples-h2-frame-logger} loggers at
+ * {@link io.servicetalk.logging.api.LogLevel#TRACE TRACE} level. Wire logging is configured to include logging of all
+ * user data contained in the payload, see {@link #LOG_USER_DATA}.
  *
  * <p>When configured correctly the output should be similar to the following:
  * <pre>
@@ -136,6 +138,19 @@ public final class DebuggingExampleServer {
         // AsyncContext.disable();
     }
 
+    /**
+     * Log all protocol user data. Logging user data may expose sensitive content contained in the headers or payload
+     * body. Care and consideration should be taken before enabling this feature on production systems.
+     *
+     * <p>If {@link Boolean#TRUE} then all user data in the headers and payload bodies will be logged in addition to
+     * network events.
+     * <p>If {@link Boolean#FALSE} then only network events will be logged, but user data contents will be omitted.
+     *
+     * <p>This implementation uses a constant function to enable or disable logging of user data, your implementation
+     * could selectively choose at runtime to log user data based upon application state or context.</p>
+     */
+    static final BooleanSupplier LOG_USER_DATA = Boolean.TRUE::booleanValue;
+
     public static void main(String... args) throws Exception {
         HttpServers.forPort(8080)
                 /*
@@ -149,14 +164,14 @@ public static void main(String... args) throws Exception {
                  * 3. Enables detailed logging of I/O and I/O states.
                  * Be sure to also enable the logger in your logging config file (log4j2.xml for this example).
                  */
-                .enableWireLogging("servicetalk-examples-wire-logger", TRACE, Boolean.TRUE::booleanValue)
+                .enableWireLogging("servicetalk-examples-wire-logger", TRACE, LOG_USER_DATA)
 
                 /*
                  * 4. Enables detailed logging of HTTP2 frames.
                  * Be sure to also enable the logger in your logging config file (log4j2.xml for this example).
                  */
                 .protocols(HttpProtocolConfigs.h2()
-                        .enableFrameLogging("servicetalk-examples-h2-frame-logger", TRACE, Boolean.TRUE::booleanValue)
+                        .enableFrameLogging("servicetalk-examples-h2-frame-logger", TRACE, LOG_USER_DATA)
                         .build())
                 .listenAndAwait((ctx, request, responseFactory) -> {
                     String who = request.payloadBody(textSerializerUtf8());

servicetalk-examples/http/debugging/src/main/java/io/servicetalk/examples/http/debugging/package-info.java

@@ -0,0 +1,21 @@
+/*
+ * Copyright © 2022 Apple Inc. and the ServiceTalk project authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+@ElementsAreNonnullByDefault
+package io.servicetalk.examples.http.debugging;
+
+import io.servicetalk.annotations.ElementsAreNonnullByDefault; /**
+ * Async "Hello World" example extended to demonstrate configuring of debugging features.
+ */

servicetalk-http-api/src/main/java/io/servicetalk/http/api/HttpServerBuilder.java

@@ -100,7 +100,7 @@ public interface HttpServerBuilder {
      * @param loggerName The name of the logger to log wire events.
      * @param logLevel The level to log at.
      * @param logUserData {@code true} to include user data (e.g. data, headers, etc.). {@code false} to exclude user
-     * data and log only network events.
+     * data and log only network events. This method is invoked for each data object allowing for dynamic behavior.
      * @return {@code this}.
      */
     HttpServerBuilder enableWireLogging(String loggerName, LogLevel logLevel, BooleanSupplier logUserData);

servicetalk-http-api/src/main/java/io/servicetalk/http/api/SingleAddressHttpClientBuilder.java

@@ -75,7 +75,7 @@ default SingleAddressHttpClientBuilder<U, R> proxyAddress(U proxyAddress) {
      * @param loggerName The name of the logger to log wire events.
      * @param logLevel The level to log at.
      * @param logUserData {@code true} to include user data (e.g. data, headers, etc.). {@code false} to exclude user
-     * data and log only network events.
+     * data and log only network events. This method is invoked for each data object allowing for dynamic behavior.
      * @return {@code this}.
      */
     SingleAddressHttpClientBuilder<U, R> enableWireLogging(String loggerName,

servicetalk-http-netty/src/main/java/io/servicetalk/http/netty/H2ProtocolConfigBuilder.java

@@ -80,7 +80,7 @@ public H2ProtocolConfigBuilder headersSensitivityDetector(
      * @param loggerName provides the logger to log HTTP/2 frames.
      * @param logLevel the level to log HTTP/2 frames.
      * @param logUserData {@code true} to include user data (e.g. data, headers, etc.). {@code false} to exclude user
-     * data and log only network events.
+     * data and log only network events. This method is invoked for each data object allowing for dynamic behavior.
      * @return {@code this}
      */
     public H2ProtocolConfigBuilder enableFrameLogging(final String loggerName,

servicetalk-opentracing-zipkin-publisher/src/main/java/io/servicetalk/opentracing/zipkin/publisher/reporter/UdpReporter.java

@@ -154,7 +154,7 @@ public Builder executor(Executor executor) {
          * @param loggerName The name of the logger to log wire events.
          * @param logLevel The level to log at.
          * @param logUserData {@code true} to include user data. {@code false} to exclude user data and log only
-         * network events.
+         * network events. This method is invoked for each data object allowing for dynamic behavior.
          * @return {@code this}
          */
         public Builder enableWireLogging(String loggerName, LogLevel logLevel, BooleanSupplier logUserData) {

servicetalk-tcp-netty-internal/src/main/java/io/servicetalk/tcp/netty/internal/AbstractTcpConfig.java

@@ -123,12 +123,12 @@ public final void flushStrategy(final FlushStrategy flushStrategy) {
     }
 
     /**
-     * Enable wire-logging for all connections. All wire events will be logged at trace level.
+     * Enable wire-logging for all connections.
      *
      * @param loggerName provides the logger to log data/events to/from the wire.
      * @param logLevel the level to log data/events to/from the wire.
      * @param logUserData {@code true} to include user data (e.g. data, headers, etc.). {@code false} to exclude user
-     * data and log only network events.
+     * data and log only network events. This method is invoked for each data object allowing for dynamic behavior.
      */
     public final void enableWireLogging(final String loggerName,
                                         final LogLevel logLevel,