diff --git a/akka-cluster/src/main/resources/reference.conf b/akka-cluster/src/main/resources/reference.conf index 3dc83b0db4..978438b4be 100644 --- a/akka-cluster/src/main/resources/reference.conf +++ b/akka-cluster/src/main/resources/reference.conf @@ -26,6 +26,10 @@ akka { # unreachable nodes as DOWN after a configured time of unreachability? # Using auto-down implies that two separate clusters will automatically be # formed in case of network partition. + # + # Don't enable this in production, see 'Auto-downing (DO NOT USE)' section + # of Akka Cluster documentation. + # # Disable with "off" or specify a duration to enable auto-down. # If a downing-provider-class is configured this setting is ignored. auto-down-unreachable-after = off diff --git a/akka-cluster/src/main/scala/akka/cluster/AutoDown.scala b/akka-cluster/src/main/scala/akka/cluster/AutoDown.scala index 6274ae8d3a..8bfab0f59e 100644 --- a/akka-cluster/src/main/scala/akka/cluster/AutoDown.scala +++ b/akka-cluster/src/main/scala/akka/cluster/AutoDown.scala @@ -10,6 +10,7 @@ import scala.concurrent.duration.FiniteDuration import akka.cluster.ClusterEvent._ import scala.concurrent.duration.Duration +import akka.actor.ActorLogging /** * INTERNAL API @@ -51,7 +52,7 @@ final class AutoDowning(system: ActorSystem) extends DowningProvider { * able to unit test the logic without running cluster. */ private[cluster] class AutoDown(autoDownUnreachableAfter: FiniteDuration) - extends AutoDownBase(autoDownUnreachableAfter) { + extends AutoDownBase(autoDownUnreachableAfter) with ActorLogging { val cluster = Cluster(context.system) import cluster.InfoLogger._ @@ -62,6 +63,8 @@ private[cluster] class AutoDown(autoDownUnreachableAfter: FiniteDuration) // re-subscribe when restart override def preStart(): Unit = { + log.warning("Don't use auto-down feature of Akka Cluster in production. " + + "See 'Auto-downing (DO NOT USE)' section of Akka Cluster documentation.") cluster.subscribe(self, classOf[ClusterDomainEvent]) super.preStart() } @@ -72,7 +75,9 @@ private[cluster] class AutoDown(autoDownUnreachableAfter: FiniteDuration) override def down(node: Address): Unit = { require(leader) - logInfo("Leader is auto-downing unreachable node [{}]", node) + logInfo("Leader is auto-downing unreachable node [{}]. " + + "Don't use auto-down feature of Akka Cluster in production. " + + "See 'Auto-downing (DO NOT USE)' section of Akka Cluster documentation.", node) cluster.down(node) } @@ -162,4 +167,4 @@ private[cluster] abstract class AutoDownBase(autoDownUnreachableAfter: FiniteDur pendingUnreachable -= node } -} \ No newline at end of file +} diff --git a/akka-docs/rst/intro/getting-started.rst b/akka-docs/rst/intro/getting-started.rst index 08191b0006..65d346a765 100644 --- a/akka-docs/rst/intro/getting-started.rst +++ b/akka-docs/rst/intro/getting-started.rst @@ -8,7 +8,7 @@ Akka requires that you have `Java 8 `_ provides a commercial build of Akka and related projects such as Scala or Play -as part of the `Reactive Platform `_ which is made available +as part of the `Lightbend Reactive Platform `_ which is made available for Java 6 in case your project can not upgrade to Java 8 just yet. It also includes additional commercial features or libraries. Getting Started Guides and Template Projects diff --git a/akka-docs/rst/java/cluster-sharding.rst b/akka-docs/rst/java/cluster-sharding.rst index aa130ddc8f..f272fed48a 100644 --- a/akka-docs/rst/java/cluster-sharding.rst +++ b/akka-docs/rst/java/cluster-sharding.rst @@ -25,6 +25,12 @@ to route the message with the entity id to the final destination. Cluster sharding will not be active on members with status :ref:`WeaklyUp ` if that feature is enabled. +.. warning:: + **Don't use Cluster Sharding together with Automatic Downing**, + since it allows the cluster to split up into two separate clusters, which in turn will result + in *multiple shards and entities* being started, one in each separate cluster! + See :ref:`automatic-vs-manual-downing-java`. + An Example ---------- @@ -304,6 +310,12 @@ cannot startup because of corrupt data, which may happen if accidentally two clusters were running at the same time, e.g. caused by using auto-down and there was a network partition. +.. warning:: + **Don't use Cluster Sharding together with Automatic Downing**, + since it allows the cluster to split up into two separate clusters, which in turn will result + in *multiple shards and entities* being started, one in each separate cluster! + See :ref:`automatic-vs-manual-downing-java`. + Use this program as a standalone Java main program:: java -classpath diff --git a/akka-docs/rst/java/cluster-singleton.rst b/akka-docs/rst/java/cluster-singleton.rst index 64d6327a6c..f4d5457050 100644 --- a/akka-docs/rst/java/cluster-singleton.rst +++ b/akka-docs/rst/java/cluster-singleton.rst @@ -73,7 +73,7 @@ Especially the last point is something you should be aware of — in general whe you should take care of downing nodes yourself and not rely on the timing based auto-down feature. .. warning:: - **Be very careful when using Cluster Singleton together with Automatic Downing**, + **Don't use Cluster Singleton together with Automatic Downing**, since it allows the cluster to split up into two separate clusters, which in turn will result in *multiple Singletons* being started, one in each separate cluster! diff --git a/akka-docs/rst/java/cluster-usage.rst b/akka-docs/rst/java/cluster-usage.rst index 0c88ea0ce7..f6b8362c8b 100644 --- a/akka-docs/rst/java/cluster-usage.rst +++ b/akka-docs/rst/java/cluster-usage.rst @@ -126,8 +126,8 @@ be allowed to join. .. _automatic-vs-manual-downing-java: -Automatic vs. Manual Downing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Downing +^^^^^^^ When a member is considered by the failure detector to be unreachable the leader is not allowed to perform its duties, such as changing status of @@ -138,7 +138,17 @@ can be performed automatically or manually. By default it must be done manually, It can also be performed programmatically with ``Cluster.get(system).down(address)``. -You can enable automatic downing with configuration:: +A pre-packaged solution for the downing problem is provided by +`Split Brain Resolver `_, +which is part of the `Lightbend Reactive Platform `_. +If you don’t use RP, you should anyway carefully read the `documentation `_ +of the Split Brain Resolver and make sure that the solution you are using handles the concerns +described there. + +Auto-downing (DO NOT USE) +------------------------- + +There is an atomatic downing feature that you should not use in production. For testing purpose you can enable it with configuration:: akka.cluster.auto-down-unreachable-after = 120s @@ -157,19 +167,8 @@ can also happen because of long GC pauses or system overload. We recommend against using the auto-down feature of Akka Cluster in production. This is crucial for correct behavior if you use :ref:`cluster-singleton-java` or :ref:`cluster_sharding_java`, especially together with Akka :ref:`persistence-java`. - -A pre-packaged solution for the downing problem is provided by -`Split Brain Resolver `_, -which is part of the Lightbend Reactive Platform. If you don’t use RP, you should anyway carefully -read the `documentation `_ -of the Split Brain Resolver and make sure that the solution you are using handles the concerns -described there. - -.. note:: If you have *auto-down* enabled and the failure detector triggers, you - can over time end up with a lot of single node clusters if you don't put - measures in place to shut down nodes that have become ``unreachable``. This - follows from the fact that the ``unreachable`` node will likely see the rest of - the cluster as ``unreachable``, become its own leader and form its own cluster. + For Akka Persistence with Cluster Sharding it can result in corrupt data in case + of network partitions. Leaving ^^^^^^^ diff --git a/akka-docs/rst/java/stream/stages-overview.rst b/akka-docs/rst/java/stream/stages-overview.rst index 166d2323cf..228ac0b580 100644 --- a/akka-docs/rst/java/stream/stages-overview.rst +++ b/akka-docs/rst/java/stream/stages-overview.rst @@ -588,7 +588,7 @@ it returns false the element is discarded. **completes** when upstream completes filterNot -^^^^^^^^ +^^^^^^^^^ Filter the incoming elements using a predicate. If the predicate returns false the element is passed downstream, if it returns true the element is discarded. diff --git a/akka-docs/rst/scala/cluster-sharding.rst b/akka-docs/rst/scala/cluster-sharding.rst index 875c216bdd..f9e7a2b0c6 100644 --- a/akka-docs/rst/scala/cluster-sharding.rst +++ b/akka-docs/rst/scala/cluster-sharding.rst @@ -25,6 +25,12 @@ to route the message with the entity id to the final destination. Cluster sharding will not be active on members with status :ref:`WeaklyUp ` if that feature is enabled. +.. warning:: + **Don't use Cluster Sharding together with Automatic Downing**, + since it allows the cluster to split up into two separate clusters, which in turn will result + in *multiple shards and entities* being started, one in each separate cluster! + See :ref:`automatic-vs-manual-downing-java`. + An Example ---------- @@ -306,6 +312,12 @@ cannot startup because of corrupt data, which may happen if accidentally two clusters were running at the same time, e.g. caused by using auto-down and there was a network partition. +.. warning:: + **Don't use Cluster Sharding together with Automatic Downing**, + since it allows the cluster to split up into two separate clusters, which in turn will result + in *multiple shards and entities* being started, one in each separate cluster! + See :ref:`automatic-vs-manual-downing-scala`. + Use this program as a standalone Java main program:: java -classpath diff --git a/akka-docs/rst/scala/cluster-singleton.rst b/akka-docs/rst/scala/cluster-singleton.rst index 50cfdd1900..8b7406b56b 100644 --- a/akka-docs/rst/scala/cluster-singleton.rst +++ b/akka-docs/rst/scala/cluster-singleton.rst @@ -73,7 +73,7 @@ Especially the last point is something you should be aware of — in general whe you should take care of downing nodes yourself and not rely on the timing based auto-down feature. .. warning:: - **Be very careful when using Cluster Singleton together with Automatic Downing**, + **Don't use Cluster Singleton together with Automatic Downing**, since it allows the cluster to split up into two separate clusters, which in turn will result in *multiple Singletons* being started, one in each separate cluster! diff --git a/akka-docs/rst/scala/cluster-usage.rst b/akka-docs/rst/scala/cluster-usage.rst index f4243805b3..da89399565 100644 --- a/akka-docs/rst/scala/cluster-usage.rst +++ b/akka-docs/rst/scala/cluster-usage.rst @@ -121,8 +121,8 @@ be allowed to join. .. _automatic-vs-manual-downing-scala: -Automatic vs. Manual Downing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Downing +^^^^^^^ When a member is considered by the failure detector to be unreachable the leader is not allowed to perform its duties, such as changing status of @@ -133,7 +133,17 @@ can be performed automatically or manually. By default it must be done manually, It can also be performed programmatically with ``Cluster(system).down(address)``. -You can enable automatic downing with configuration:: +A pre-packaged solution for the downing problem is provided by +`Split Brain Resolver `_, +which is part of the `Lightbend Reactive Platform `_. +If you don’t use RP, you should anyway carefully read the `documentation `_ +of the Split Brain Resolver and make sure that the solution you are using handles the concerns +described there. + +Auto-downing (DO NOT USE) +------------------------- + +There is an atomatic downing feature that you should not use in production. For testing purpose you can enable it with configuration:: akka.cluster.auto-down-unreachable-after = 120s @@ -152,19 +162,9 @@ can also happen because of long GC pauses or system overload. We recommend against using the auto-down feature of Akka Cluster in production. This is crucial for correct behavior if you use :ref:`cluster-singleton-scala` or :ref:`cluster_sharding_scala`, especially together with Akka :ref:`persistence-scala`. + For Akka Persistence with Cluster Sharding it can result in corrupt data in case + of network partitions. -A pre-packaged solution for the downing problem is provided by -`Split Brain Resolver `_, -which is part of the Lightbend Reactive Platform. If you don’t use RP, you should anyway carefully -read the `documentation `_ -of the Split Brain Resolver and make sure that the solution you are using handles the concerns -described there. - -.. note:: If you have *auto-down* enabled and the failure detector triggers, you - can over time end up with a lot of single node clusters if you don't put - measures in place to shut down nodes that have become ``unreachable``. This - follows from the fact that the ``unreachable`` node will likely see the rest of - the cluster as ``unreachable``, become its own leader and form its own cluster. Leaving ^^^^^^^ diff --git a/akka-docs/rst/scala/dispatchers.rst b/akka-docs/rst/scala/dispatchers.rst index 83d53776e8..a1caf2cc6f 100644 --- a/akka-docs/rst/scala/dispatchers.rst +++ b/akka-docs/rst/scala/dispatchers.rst @@ -70,6 +70,7 @@ of programmatically provided parameter. .. _ForkJoinPool documentation: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ForkJoinPool.html .. _ThreadPoolExecutor documentation: https://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ThreadPoolExecutor.html + Types of dispatchers -------------------- diff --git a/akka-docs/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst b/akka-docs/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst index 7bc199dc36..532f3c1192 100644 --- a/akka-docs/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst +++ b/akka-docs/rst/scala/http/routing-dsl/directives/debugging-directives/logRequestResult.rst @@ -36,7 +36,7 @@ Building Advanced Directives ---------------------------- This example will showcase the advanced logging using the ``DebuggingDirectives``. -The built `logResponseTime ` directive will log the request time (or rejection reason): +The built `logResponseTime` directive will log the request time (or rejection reason): .. includecode2:: ../../../../code/docs/http/scaladsl/server/directives/DebuggingDirectivesExamplesSpec.scala :snippet: logRequestResultWithResponseTime