Revisit the logging documentation

docs/modules/ROOT/pages/user-guide/configuration.adoc

@@ -7,6 +7,18 @@ Each extension documents its options at the bottom of its xref:reference/index.a
 The configuration options can be set in `application.properties` file or via environment variables - see
 {link-quarkus-docs-base}/config-reference[Quarkus configuration reference] for details.
 
+[[declarative-vs-programmatic-configuration]]
+== Declarative vs. programmatic configuration
+
+The declarative configuration set via `application.properties` or via environment variables typically causes
+creation and/or configuration of some CXF objects,
+such as `org.apache.cxf.ext.logging.LoggingFeature`, `org.apache.cxf.metrics.MetricsFeature`, `org.apache.cxf.configuration.jsse.TLSClientParameters` or similar.
+Unless explicitly stated in the documentation, the whole life cycle of those objects is controlled by {quarkus-cxf-project-name}.
+To prevent non-deterministic behavior, you should not mutate those objects even if they are accessible via public API of CXF.
+
+If you need more flexibility, you should avoid configuring the given feature declaratively
+and rather switch to purely programmatic approach.
+
 [[beanRefs]]
 == Bean references
 
@@ -15,7 +27,6 @@ xref:user-guide/interceptors-features-handlers/cxf-interceptors-and-features.ado
 
 There are two ways how to set a bean reference in the configuration: by type or by bean name.
 
-
 === Bean reference by type
 
 Here is an example:

docs/modules/ROOT/pages/user-guide/first-soap-web-service.adoc

@@ -151,33 +151,19 @@ $ curl -v -X POST -H "Content-Type: text/xml;charset=UTF-8" \
 You can see the expected `<return>Hello World!</return>` in the SOAP response.
 
 [[logging-feature]]
-== Add the logging feature while dev mode is running
+== Enable payload logging while dev mode is running
 
 Sometimes it may come in handy to be able to inspect the SOAP messages received or sent by the server or client.
-This is easily doable by adding the `quarkus-cxf-rt-features-logging` extension to `pom.xml`.
+This is easily doable by enabling the xref:user-guide/payload-logging.adoc[logging] feature in `application.properties`:
 
-[TIP]
-====
-Try to do that while Quarkus dev mode is running.
-You should see the application being recompiled and redeployed upon saving your changes in the source tree.
-====
-
-.Add this to `pom.xml`
-[source,xml,subs=attributes+]
-----
-<dependency>
-    <groupId>io.quarkiverse.cxf</groupId>
-    <artifactId>quarkus-cxf-rt-features-logging</artifactId>
-</dependency>
-----
-
-.Enable SOAP payload logging in `application.properties`
+.application.properties
 [source,xml,subs=attributes+]
 ----
-quarkus.cxf.endpoint."/hello".features=org.apache.cxf.ext.logging.LoggingFeature
+quarkus.cxf.logging.enabled-for = services
+# other possible values are clients, both and none
 ----
 
-After that you can send a new SOAP request and see some SOAP payloads in the application console:
+After that, you can send a new SOAP request and see some SOAP payloads in the console:
 
 [source,shell]
 ----

docs/modules/ROOT/pages/user-guide/payload-logging.adoc

@@ -12,7 +12,7 @@ Refer to Quarkus {link-quarkus-docs-base}/logging[Logging guide] for basic infor
 == Payload logging
 
 [NOTE]
-.History
+.Historical note
 ====
 Since {quarkus-cxf-project-name} 2.6.0, the payload logging functionality is available via
 `io.quarkiverse.cxf:quarkus-cxf` extension.
@@ -37,7 +37,7 @@ There are four possible values:
 * `services` - the global logging feature is enabled for all service endpoints in the application
 * `both` - the global logging feature is enabled for all clients and service endpoints in the application
 
-The global settings can be xref:#per-client-or-service-endpoind-payload-logging[overriden] on the client or service endpoint level.
+Here is an example:
 
 .application.properties
 [source,properties,subs=attributes+]
@@ -47,6 +47,8 @@ quarkus.cxf.logging.enabled-for = both
 quarkus.cxf.logging.pretty = true
 ----
 
+The global settings can be xref:#per-client-or-service-endpoind-payload-logging[overriden] on the client or service endpoint level.
+
 All logging configuration options are listed on `xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-logging-enabled-for[quarkus-cxf]` reference page.
 
 [TIP]
@@ -67,54 +69,32 @@ endpoint declaratively by setting the appropriate options in `application.proper
 [source,properties,subs=attributes+]
 ----
 # For a service:
-quarkus.cxf.endpoint."/hello".logging.enabled = true
-quarkus.cxf.endpoint."/hello".logging.pretty = true
+quarkus.cxf.endpoint."/hello".logging.enabled = pretty
+quarkus.cxf.endpoint."/hello".logging.limit = 256
 # For a client:
-quarkus.cxf.client.hello.logging.enabled = true
-quarkus.cxf.client.hello.logging.pretty = true
+quarkus.cxf.client.hello.logging.enabled = pretty
+quarkus.cxf.client.hello.logging.sensitive-protocol-header-names = X-my-secret
 ----
 
+[TIP]
+====
+`*.logging.enabled = pretty` is a shorthand for `*.logging.enabled = true` and `*.logging.pretty = true`.
+====
+
 All logging configuration options are documented on `quarkus-cxf` reference page:
 
 * xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-client-client-name-logging-enabled[For clients]
 * xref:reference/extensions/quarkus-cxf.adoc#quarkus-cxf_quarkus-cxf-endpoint-endpoint-path-logging-enabled[For service endpoints]
 
 == Alternative ways of adding a `LoggingFeature` to a client or service
 
-To attach an instance with default settings, you can do one of the following:
+The `quarkus.cxf*.logging.*` configuration options mentioned above will configure an internal instance of `LoggingFeature`
+and attach it to the respective client or service.
+There is no way how you can interact with this internal instance of `LoggingFeature` programmatically.
 
-1. In `application.properties`:
-+
-[source,properties,subs=attributes+]
-----
-# For a service:
-quarkus.cxf.endpoint."/hello".features = org.apache.cxf.ext.logging.LoggingFeature
-# For a client:
-quarkus.cxf.client."myClient".features = org.apache.cxf.ext.logging.LoggingFeature
-----
-+
-[TIP]
-====
-There is an example in xref:user-guide/first-soap-web-service.adoc#logging-feature[Your first SOAP Web service] chapter of the User guide.
-====
-+
-or alternatively
-+
-2. Use the `@Features` annotation of CXF:
-+
-[source,java]
-----
-@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
-@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
-public class SayHiImplementation implements SayHi {
-   public long sayHi(long arg) {
-       return arg;
-   }
-   //...
-}
-----
+If you need more control or if you migrate from other platforms, some of the following options may come in handy.
 
-=== Producing a custom `LoggingFeature` bean
+=== Produce a custom `LoggingFeature` bean
 
 If you need some custom logic to setup the `LoggingFeature`, you can produce a named `LoggingFeature` bean:
 
@@ -147,3 +127,20 @@ quarkus.cxf.endpoint."/hello".features = #limitedLoggingFeature
 # For a client:
 quarkus.cxf.client.hello.features = #limitedLoggingFeature
 ----
+
+=== `@Features` annotation of CXF
+
+The `@org.apache.cxf.feature.Features` annotation of CXF works too.
+Here is how you can set an uncustomized instance of `LoggingFeature` on a service implementation class.
+
+[source,java]
+----
+@org.apache.cxf.feature.Features (features = {"org.apache.cxf.ext.logging.LoggingFeature"})
+@WebService(endpointInterface = "org.acme.SayHi", targetNamespace = "uri:org.acme")
+public class SayHiImplementation implements SayHi {
+   public long sayHi(long arg) {
+       return arg;
+   }
+   //...
+}
+----