+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/scala/stream/stream-customize.rst

@@ -300,6 +300,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.
+
+The helper trait ``akka.stream.stage.StageLogging`` is provided to enable you to easily obtain a ``LoggingAdapter``
+inside of a ``GraphStage`` as long as the ``Materializer`` you're using is able to provide you with a logger.
+In that sense, it serves a very similar purpose as ``ActorLogging`` does for Actors. 
+
+.. 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-scala` 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/GraphStageLoggingDocSpec.scala#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
 ------------