[#3656] Add Message Tracing logs

adapters/coap/src/main/java/org/eclipse/hono/adapter/coap/AbstractVertxBasedCoapAdapter.java

@@ -20,6 +20,7 @@
 import org.eclipse.californium.core.CoapServer;
 import org.eclipse.californium.core.coap.CoAP;
 import org.eclipse.californium.core.network.Endpoint;
+import org.eclipse.californium.core.network.interceptors.MessageTracer;
 import org.eclipse.californium.core.server.resources.Resource;
 import org.eclipse.hono.adapter.AbstractProtocolAdapterBase;
 import org.eclipse.hono.util.Constants;
@@ -198,13 +199,19 @@ protected Resource createRoot() {
                     final Future<Endpoint> secureEndpointFuture = endpointFactory.getSecureEndpoint()
                             .onFailure(t -> log.info("not creating secure endpoint: {}", t.getMessage()))
                             .onSuccess(ep -> {
+                                if (getConfig().isMessageTracingLogEnabled()) {
+                                    ep.addInterceptor(new MessageTracer());
+                                }
                                 ep.addInterceptor(internalErrorTracer);
                                 newServer.addEndpoint(ep);
                                 this.secureEndpoint = ep;
                             });
                     final Future<Endpoint> insecureEndpointFuture = endpointFactory.getInsecureEndpoint()
                             .onFailure(t -> log.info("not creating insecure endpoint: {}", t.getMessage()))
                             .onSuccess(ep -> {
+                                if (getConfig().isMessageTracingLogEnabled()) {
+                                    ep.addInterceptor(new MessageTracer());
+                                }
                                 ep.addInterceptor(internalErrorTracer);
                                 newServer.addEndpoint(ep);
                                 this.insecureEndpoint = ep;

adapters/coap/src/main/java/org/eclipse/hono/adapter/coap/CoapAdapterOptions.java

@@ -152,4 +152,14 @@ public interface CoapAdapterOptions {
      */
     @WithDefault("500")
     int timeoutToAck();
+
+    /**
+     * Checks, if message tracing log is enabled.
+     * <p>
+     * When enabled, the CoAP adapter will log all incoming and outgoing messages tracing information.
+     *
+     * @return {@code true} enable message tracing log, {@code false} disable message tracing log.
+     */
+    @WithDefault("false")
+    boolean messageTracingLogEnabled();
 }

adapters/coap/src/main/java/org/eclipse/hono/adapter/coap/CoapAdapterProperties.java

@@ -66,6 +66,11 @@ public class CoapAdapterProperties extends ProtocolAdapterProperties {
      * that time, the status gets removed and a new request will fail.
      */
     public static final int DEFAULT_BLOCKWISE_STATUS_LIFETIME = 300000;
+    /**
+     * The default for message tracing log. When message tracing is enabled, the CoAP adapter
+     * will log all incoming and outgoing messages. This is useful for debugging purposes.
+     */
+    public static final boolean DEFAULT_MESSAGE_TRACING_LOG = false;
 
     static {
         DEFAULT_CONNECTOR_THREADS = 2;
@@ -91,6 +96,7 @@ public class CoapAdapterProperties extends ProtocolAdapterProperties {
     private int blockwiseStatusLifetime = DEFAULT_BLOCKWISE_STATUS_LIFETIME;
     private boolean messageOffloadingEnabled = DEFAULT_MESSAGE_OFFLOADING;
     private int timeoutToAck = DEFAULT_TIMEOUT_TO_ACK;
+    private boolean messageTracingLogEnabled = DEFAULT_MESSAGE_TRACING_LOG;
 
     /**
      * Creates properties using default values.
@@ -117,6 +123,7 @@ public CoapAdapterProperties(final CoapAdapterOptions options) {
         this.networkConfig = options.networkConfig().orElse(null);
         this.secureNetworkConfig = options.secureNetworkConfig().orElse(null);
         setTimeoutToAck(options.timeoutToAck());
+        this.messageTracingLogEnabled = options.messageTracingLogEnabled();
     }
 
     /**
@@ -466,4 +473,27 @@ public final void setTimeoutToAck(final int timeoutToAck) {
         }
         this.timeoutToAck = timeoutToAck;
     }
+
+    /**
+     * Returns the current message tracing log mode.
+     * <p>
+     * When message tracing is enabled, the CoAP adapter will log all incoming and outgoing messages.
+     * <p>
+     * @return {@code true} if message tracing log is enabled, {@code false} if it's disabled.
+     */
+    public final boolean isMessageTracingLogEnabled() {
+        return messageTracingLogEnabled;
+    }
+
+    /**
+     * Sets the message tracing log mode.
+     * <p>
+     * When message tracing is enabled, the CoAP adapter will log all incoming and outgoing messages.
+     * Setting this property has effect only during the application startup.
+     * <p>
+     * @param messageTracingLog {@code true} enable message tracing log, {@code false} disable message tracing log.
+     */
+    public final void setMessageTracingLogEnabled(final boolean messageTracingLog) {
+        this.messageTracingLogEnabled = messageTracingLog;
+    }
 }

site/documentation/content/admin-guide/coap-adapter-config.md

@@ -45,6 +45,7 @@ configuring the CoAP adapter.
 | `HONO_COAP_MAXCONNECTIONS`<br>`hono.coap.maxConnections` | no | `0` | The maximum number of concurrent DTLS connections that the protocol adapter should accept. If set to `0`, the protocol adapter determines a reasonable value based on the available resources like memory and CPU. |
 | `HONO_COAP_MAXPAYLOADSIZE`<br>`hono.coap.maxPayloadSize` | no | `2048` | The maximum allowed size of an incoming CoAP request's body in bytes. Requests with a larger body size are rejected with a 4.13 `Request entity too large` response. |
 | `HONO_COAP_MESSAGEOFFLOADINGENABLED`<br>`hono.coap.messageOffloadingEnabled` | no | true | Enables to clear payload and serialized messages kept for deduplication in order to reduce the heap consumption. Experimental. |
+| `HONO_COAP_MESSAGETRACINGLOGENABLED`<br>`hono.coap.messageTracingLogEnabled` | no | `false` | If set to `true` the protocol adapter will start to log every incoming and outgoing CoAP messages with tracing information (message connection information, request code, confirmable and confirmed details, MID, token, options, status and the payload partially). |
 | `HONO_COAP_NETWORKCONFIG`<br>`hono.coap.networkConfig` | no | - | The absolute path to a Californium properties file containing network configuration properties that should be used for the insecure and secure CoAP port. If not set, Californium's default properties will be used. Values may be overwritten using the specific `HONO_COAP_INSECURENETWORKCONFIG` or `HONO_COAP_SECURENETWORKCONFIG`. If the file is not available, not readable or malformed, the adapter will fail to start. |
 | `HONO_COAP_PORT`<br>`hono.coap.port` | no | - | The secure port that the protocol adapter should listen on.<br>See [Port Configuration]({{< relref "#port-configuration" >}}) below for details. |
 | `HONO_COAP_SECURENETWORKCONFIG`<br>`hono.coap.secureNetworkConfig` | no | - | The absolute path to a Californium properties file containing network configuration properties that should be used for the secure CoAP port. If not set, Californium's default properties will be used. If the file is not available, not readable or malformed, the adapter will fail to start. |