LifecycleObserver examples: clarify server-side ordering options (#3087)

Motivation:

Server-side has 2 options on how to configure an observer.

Modifications:

- Demonstrate both options;
- Add more clarification comments and point to javadoc for more info;
- Make HTTP and gRPC observer examples consistent;

Result:

Observer examples show all possible configuration options and clarify
differences.

servicetalk-examples/grpc/observer/src/main/java/io/servicetalk/examples/grpc/observer/LifecycleObserverServer.java

@@ -33,14 +33,19 @@ public static void main(String... args) throws Exception {
         GrpcLifecycleObserver observer =
                 GrpcLifecycleObservers.logging("servicetalk-examples-grpc-observer-logger", TRACE);
         GrpcServers.forPort(8080)
-                // Option 1: apply an observer for entire server to capture processing by all filters:
+                // There are a few ways how to configure an observer depending on the desired scope of its visibility.
+                // 1. Configuring it at the builder gives maximum visibility and captures entire request-response state,
+                // including all filters and exception mappers.
                 .lifecycleObserver(observer)
-                // Option 2: apply an observer using a filter to move it later in a filter chain (before/after tracing
-                // info is available or retry/timeout/authentication/exception-mapping filters applied), or to apply it
-                // conditionally:
+                // 2. Configuring it as a filter allows users to change the ordering of the observer compare to other
+                // filters or make it conditional. This might be helpful in a few scenarios such as when the tracking
+                // scope should be limited or when logging should include tracing/MDC context set by other preceding
+                // filters. See javadoc of GrpcLifecycleObserverServiceFilter for more details.
                 // .initializeHttp(builder -> builder
-                        // .appendNonOffloadingServiceFilter(tracingFilter)
-                        // .appendNonOffloadingServiceFilter(new GrpcLifecycleObserverServiceFilter(observer)))
+                        // 2.a. At any position compare to other filters before offloading:
+                        // .appendNonOffloadingServiceFilter(new GrpcLifecycleObserverServiceFilter(observer))
+                        // 2.b. At any position compare to other filters after offloading:
+                        // .appendServiceFilter(new GrpcLifecycleObserverServiceFilter(observer)))
                 .listenAndAwait((GreeterService) (ctx, request) ->
                         succeeded(HelloReply.newBuilder().setMessage("Hello " + request.getName()).build()))
                 .awaitShutdown();

servicetalk-examples/http/observer/src/main/java/io/servicetalk/examples/http/observer/LifecycleObserverServer.java

@@ -27,10 +27,21 @@
  */
 public final class LifecycleObserverServer {
     public static void main(String[] args) throws Exception {
+        HttpLifecycleObserver observer = HttpLifecycleObservers.logging(
+                "servicetalk-examples-http-observer-logger", TRACE);
         HttpServers.forPort(8080)
-                .lifecycleObserver(HttpLifecycleObservers.logging("servicetalk-examples-http-observer-logger", TRACE))
-                // Note: this example demonstrates only blocking-aggregated programming paradigm, for asynchronous and
-                // streaming API see helloworld examples.
+                // There are a few ways how to configure an observer depending on the desired scope of its visibility.
+                // 1. Configuring it at the builder gives maximum visibility and captures entire request-response state,
+                // including all filters and exception mappers.
+                .lifecycleObserver(observer)
+                // 2. Configuring it as a filter allows users to change the ordering of the observer compare to other
+                // filters or make it conditional. This might be helpful in a few scenarios such as when the tracking
+                // scope should be limited or when logging should include tracing/MDC context set by other preceding
+                // filters. See javadoc of HttpLifecycleObserverServiceFilter for more details.
+                // 2.a. At any position compare to other filters before offloading:
+                // .appendNonOffloadingServiceFilter(new HttpLifecycleObserverServiceFilter(observer))
+                // 2.b. At any position compare to other filters after offloading:
+                // .appendServiceFilter(new HttpLifecycleObserverServiceFilter(observer))
                 .listenBlockingAndAwait((ctx, request, responseFactory) -> responseFactory.ok()
                         .payloadBody("Hello LifecycleObserver!", textSerializerUtf8()))
                 .awaitShutdown();