+str #18793 StageLogging that allows logger access in stages (#21696)

* +str #18793 StageLogging that allows logger access in stages
Also, non ActorMaterializers can opt-into providing a logger here.

* +str #18794 add javadsl for StageLogging

* fix missing test method on compile only class

akka-docs/rst/java/code/docs/stream/GraphStageLoggingDocTest.java

@@ -0,0 +1,65 @@
+/*
+ * Copyright (C) 2016 Lightbend Inc. <http://www.lightbend.com>
+ */
+
+package docs.stream;
+
+import akka.actor.ActorSystem;
+import akka.stream.Attributes;
+import akka.stream.Materializer;
+import akka.stream.Outlet;
+import akka.stream.SourceShape;
+import akka.stream.stage.*;
+import docs.AbstractJavaTest;
+import org.junit.Test;
+
+import java.util.concurrent.ThreadLocalRandom;
+import java.util.stream.Collector;
+
+public class GraphStageLoggingDocTest extends AbstractJavaTest {
+  static ActorSystem system;
+  static Materializer mat;
+
+  @Test
+  public void compileOnlyTestClass() throws Exception { }
+  
+  //#stage-with-logging
+  public class RandomLettersSource extends GraphStage<SourceShape<String>> {
+    public final Outlet<String> out = Outlet.create("RandomLettersSource.in");
+
+    private final SourceShape<String> shape = SourceShape.of(out);
+
+    @Override
+    public SourceShape<String> shape() {
+      return shape;
+    }
+
+    @Override
+    public GraphStageLogic createLogic(Attributes inheritedAttributes) {
+      return new GraphStageLogicWithLogging(shape()) {
+
+        {
+          setHandler(out, new AbstractOutHandler() {
+            @Override
+            public void onPull() throws Exception {
+              final String s = nextChar();// ASCII lower case letters
+
+              // `log` is obtained from materializer automatically (via StageLogging)
+              log().debug("Randomly generated: [{}]", s);
+
+              push(out, s);
+            }
+
+            private String nextChar() {
+              final char i = (char) ThreadLocalRandom.current().nextInt('a', 'z' + 1);
+              return String.valueOf(i);
+            }
+
+          });
+        }
+      };
+    }
+  }
+  //#stage-with-logging
+
+}

akka-docs/rst/java/stream/stream-customize.rst

@@ -296,6 +296,29 @@ constructor and usually done in ``preStart``). In this case the stage **must** b
 or ``failStage(exception)``. This feature carries the risk of leaking streams and actors, therefore it should be used
 with care.
 
+Logging inside GraphStages
+--------------------------
+
+Logging debug or other important information in your stages is often a very good idea, especially when developing
+more advances stages which may need to be debugged at some point.
+
+You can extend the ``akka.stream.stage.GraphStageWithLogging`` or ``akka.strea.stage.TimerGraphStageWithLogging`` classes
+instead of the usual ``GraphStage`` to enable you to easily obtain a ``LoggingAdapter`` inside your stage as long as 
+the ``Materializer`` you're using is able to provide you with a logger.
+
+.. note:: 
+  Please note that you can always simply use a logging library directly inside a Stage.
+  Make sure to use an asynchronous appender however, to not accidentally block the stage when writing to files etc.
+  See :ref:`slf4j-directly-java` for more details on setting up async appenders in SLF4J.
+
+The stage then gets access to the ``log`` field which it can safely use from any ``GraphStage`` callbacks:
+
+.. includecode:: ../code/docs/stream/GraphStageLoggingDocTest.java#stage-with-logging
+
+.. note::
+  **SPI Note:** If you're implementing a Materializer, you can add this ability to your materializer by implementing 
+  ``MaterializerLoggingProvider`` in your ``Materializer``.
+
 Using timers
 ------------