Log actor failures in supervisor, see #2824

* To make it possible to override with application
  specific logging, or mute logging for certain failures
* Changed log level of Resume failures to WARNING, which
  caused all the changes to the tests

akka-docs/rst/scala/actors.rst

@@ -882,7 +882,7 @@ Please note, that the child actors are *still restarted*, but no new ``ActorRef`
 the same principles for the children, ensuring that their ``preStart()`` method is called only at the creation of their
 refs.
 
-For more information see :ref:`what-restarting-means-scala`.
+For more information see :ref:`supervision-restart`.
 
 Initialization via message passing
 ----------------------------------

akka-docs/rst/scala/code/docs/actor/FaultHandlingDocSpec.scala

@@ -93,7 +93,7 @@ class FaultHandlingDocSpec extends AkkaSpec with ImplicitSender {
       supervisor ! Props[Child]
       val child = expectMsgType[ActorRef] // retrieve answer from TestKit’s testActor
       //#create
-      EventFilter[ArithmeticException](occurrences = 1) intercept {
+      EventFilter.warning(occurrences = 1) intercept {
         //#resume
         child ! 42 // set state to 42
         child ! "get"
@@ -121,7 +121,7 @@ class FaultHandlingDocSpec extends AkkaSpec with ImplicitSender {
         child.isTerminated must be(true)
         //#stop
       }
-      EventFilter[Exception]("CRASH", occurrences = 4) intercept {
+      EventFilter[Exception]("CRASH", occurrences = 2) intercept {
         //#escalate-kill
         supervisor ! Props[Child] // create new child
         val child2 = expectMsgType[ActorRef]

akka-docs/rst/scala/fault-tolerance.rst

@@ -82,6 +82,22 @@ loss of the child. This strategy is also provided pre-packaged as
 :class:`StoppingSupervisorStrategy` configurator to be used when you want the
 ``"/user"`` guardian to apply it.
 
+Logging of Actor Failures
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default the ``SupervisorStrategy`` logs failures unless they are escalated.
+Escalated failures are supposed to be handled, and potentially logged, at a level
+higher in the hierarchy.
+
+You can mute the default logging of a ``SupervisorStrategy`` by setting
+``loggingEnabled`` to ``false`` when instantiating it. Customized logging
+can be done inside the ``Decider``. Note that the reference to the currently
+failed child is available as the ``sender`` when the ``SupervisorStrategy`` is
+declared inside the supervising actor.
+
+You may also customize the logging in your own ``SupervisorStrategy`` implementation
+by overriding the ``logFailure`` method.
+
 Supervision of Top-Level Actors
 -------------------------------