From 22b88533145265dee3d58c26ae37c813b033eb1e Mon Sep 17 00:00:00 2001 From: Patrik Nordwall Date: Fri, 4 Sep 2015 12:38:49 +0200 Subject: [PATCH] =clu #13584 mark as experimental and some doc clarificiations --- .../metrics/ClusterMetricsCollector.scala | 10 +++++++--- .../pubsub/DistributedPubSubMediator.scala | 4 ++++ .../src/main/resources/reference.conf | 1 + .../cluster/ClusterMetricsCollector.scala | 12 ++++++++---- .../src/main/scala/akka/cluster/Member.scala | 11 +++++++++++ akka-docs/rst/common/cluster.rst | 4 ++++ akka-docs/rst/java/cluster-metrics.rst | 3 +++ akka-docs/rst/java/cluster-sharding.rst | 3 +++ akka-docs/rst/java/cluster-singleton.rst | 3 +++ akka-docs/rst/java/cluster-usage.rst | 19 ++++++++++++++++++- akka-docs/rst/java/distributed-data.rst | 6 +++++- akka-docs/rst/java/distributed-pub-sub.rst | 5 +++++ akka-docs/rst/scala/cluster-metrics.rst | 3 +++ akka-docs/rst/scala/cluster-sharding.rst | 3 +++ akka-docs/rst/scala/cluster-singleton.rst | 3 +++ akka-docs/rst/scala/cluster-usage.rst | 19 ++++++++++++++++++- akka-docs/rst/scala/distributed-data.rst | 6 +++++- akka-docs/rst/scala/distributed-pub-sub.rst | 5 +++++ 18 files changed, 109 insertions(+), 11 deletions(-) diff --git a/akka-cluster-metrics/src/main/scala/akka/cluster/metrics/ClusterMetricsCollector.scala b/akka-cluster-metrics/src/main/scala/akka/cluster/metrics/ClusterMetricsCollector.scala index 7d6cbedfe3..a2fc73e04c 100644 --- a/akka-cluster-metrics/src/main/scala/akka/cluster/metrics/ClusterMetricsCollector.scala +++ b/akka-cluster-metrics/src/main/scala/akka/cluster/metrics/ClusterMetricsCollector.scala @@ -179,8 +179,10 @@ private[metrics] class ClusterMetricsCollector extends Actor with ActorLogging { case MemberRemoved(m, _) ⇒ removeMember(m) case MemberExited(m) ⇒ removeMember(m) case UnreachableMember(m) ⇒ removeMember(m) - case ReachableMember(m) ⇒ if (m.status == MemberStatus.Up) addMember(m) - case _: MemberEvent ⇒ // not interested in other types of MemberEvent + case ReachableMember(m) ⇒ + if (m.status == MemberStatus.Up || m.status == MemberStatus.WeaklyUp) + addMember(m) + case _: MemberEvent ⇒ // not interested in other types of MemberEvent } @@ -209,7 +211,9 @@ private[metrics] class ClusterMetricsCollector extends Actor with ActorLogging { * Updates the initial node ring for those nodes that are [[akka.cluster.MemberStatus]] `Up`. */ def receiveState(state: CurrentClusterState): Unit = - nodes = (state.members -- state.unreachable) collect { case m if m.status == MemberStatus.Up ⇒ m.address } + nodes = (state.members -- state.unreachable) collect { + case m if m.status == MemberStatus.Up || m.status == MemberStatus.WeaklyUp ⇒ m.address + } /** * Samples the latest metrics for the node, updates metrics statistics in diff --git a/akka-cluster-tools/src/main/scala/akka/cluster/pubsub/DistributedPubSubMediator.scala b/akka-cluster-tools/src/main/scala/akka/cluster/pubsub/DistributedPubSubMediator.scala index 1448a13aa8..d2604e4102 100644 --- a/akka-cluster-tools/src/main/scala/akka/cluster/pubsub/DistributedPubSubMediator.scala +++ b/akka-cluster-tools/src/main/scala/akka/cluster/pubsub/DistributedPubSubMediator.scala @@ -595,6 +595,10 @@ class DistributedPubSubMediator(settings: DistributedPubSubSettings) extends Act if (matchingRole(m)) nodes += m.address + case MemberWeaklyUp(m) ⇒ + if (matchingRole(m)) + nodes += m.address + case MemberRemoved(m, _) ⇒ if (m.address == selfAddress) context stop self diff --git a/akka-cluster/src/main/resources/reference.conf b/akka-cluster/src/main/resources/reference.conf index d4ea40af7a..5fb3ff3105 100644 --- a/akka-cluster/src/main/resources/reference.conf +++ b/akka-cluster/src/main/resources/reference.conf @@ -45,6 +45,7 @@ akka { # so they become part of the cluster even during a network split. The leader will # move 'WeaklyUp' members to 'Up' status once convergence has been reached. This # feature must be off if some members are running Akka 2.3.X. + # WeaklyUp is an EXPERIMENTAL feature. allow-weakly-up-members = off # The roles of this member. List of strings, e.g. roles = ["A", "B"]. diff --git a/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala b/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala index bcf35858b1..bf68babb9a 100644 --- a/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala +++ b/akka-cluster/src/main/scala/akka/cluster/ClusterMetricsCollector.scala @@ -4,7 +4,7 @@ package akka.cluster -// TODO remove metrics +// TODO remove metrics import java.io.Closeable import java.lang.System.{ currentTimeMillis ⇒ newTimestamp } @@ -24,6 +24,7 @@ import akka.actor.Address import akka.actor.DynamicAccess import akka.actor.ExtendedActorSystem import akka.cluster.MemberStatus.Up +import akka.cluster.MemberStatus.WeaklyUp import akka.event.Logging import java.lang.management.MemoryUsage @@ -89,11 +90,14 @@ private[cluster] class ClusterMetricsCollector(publisher: ActorRef) extends Acto case msg: MetricsGossipEnvelope ⇒ receiveGossip(msg) case state: CurrentClusterState ⇒ receiveState(state) case MemberUp(m) ⇒ addMember(m) + case MemberWeaklyUp(m) ⇒ addMember(m) case MemberRemoved(m, _) ⇒ removeMember(m) case MemberExited(m) ⇒ removeMember(m) case UnreachableMember(m) ⇒ removeMember(m) - case ReachableMember(m) ⇒ if (m.status == Up) addMember(m) - case _: MemberEvent ⇒ // not interested in other types of MemberEvent + case ReachableMember(m) ⇒ + if (m.status == MemberStatus.Up || m.status == MemberStatus.WeaklyUp) + addMember(m) + case _: MemberEvent ⇒ // not interested in other types of MemberEvent } @@ -122,7 +126,7 @@ private[cluster] class ClusterMetricsCollector(publisher: ActorRef) extends Acto * Updates the initial node ring for those nodes that are [[akka.cluster.MemberStatus]] `Up`. */ def receiveState(state: CurrentClusterState): Unit = - nodes = state.members collect { case m if m.status == Up ⇒ m.address } + nodes = state.members collect { case m if m.status == Up || m.status == WeaklyUp ⇒ m.address } /** * Samples the latest metrics for the node, updates metrics statistics in diff --git a/akka-cluster/src/main/scala/akka/cluster/Member.scala b/akka-cluster/src/main/scala/akka/cluster/Member.scala index d1201c8120..8dc08dde6f 100644 --- a/akka-cluster/src/main/scala/akka/cluster/Member.scala +++ b/akka-cluster/src/main/scala/akka/cluster/Member.scala @@ -168,6 +168,10 @@ abstract class MemberStatus object MemberStatus { @SerialVersionUID(1L) case object Joining extends MemberStatus + /** + * WeaklyUp is an EXPERIMENTAL feature and is subject to change until + * it has received more real world testing. + */ @SerialVersionUID(1L) case object WeaklyUp extends MemberStatus @SerialVersionUID(1L) case object Up extends MemberStatus @SerialVersionUID(1L) case object Leaving extends MemberStatus @@ -180,6 +184,13 @@ object MemberStatus { */ def joining: MemberStatus = Joining + /** + * Java API: retrieve the “weaklyUp” status singleton. + * WeaklyUp is an EXPERIMENTAL feature and is subject to change until + * it has received more real world testing. + */ + def weaklyUp: MemberStatus = WeaklyUp + /** * Java API: retrieve the “up” status singleton */ diff --git a/akka-docs/rst/common/cluster.rst b/akka-docs/rst/common/cluster.rst index 1ad18cb3dd..ff1becd6f6 100644 --- a/akka-docs/rst/common/cluster.rst +++ b/akka-docs/rst/common/cluster.rst @@ -280,6 +280,10 @@ promoted while convergence is not yet reached. These ``Joining`` nodes will be promoted as ``WeaklyUp``. Once gossip convergence is reached, the leader will move ``WeaklyUp`` members to ``Up``. +Note that members on the other side of a network partition have no knowledge about +the existence of the new members. You should for example not count ``WeaklyUp`` +members in quorum decisions. + State Diagram for the Member States (``akka.cluster.allow-weakly-up-members=off``) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/akka-docs/rst/java/cluster-metrics.rst b/akka-docs/rst/java/cluster-metrics.rst index 33d90ade46..5c6ad4a75c 100644 --- a/akka-docs/rst/java/cluster-metrics.rst +++ b/akka-docs/rst/java/cluster-metrics.rst @@ -32,6 +32,9 @@ and add the following configuration stanza to your ``application.conf`` Make sure to disable legacy metrics in akka-cluster: ``akka.cluster.metrics.enabled=off``, since it is still enabled in akka-cluster by default (for compatibility with past releases). + +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will participate in Cluster Metrics collection and dissemination. Metrics Collector ----------------- diff --git a/akka-docs/rst/java/cluster-sharding.rst b/akka-docs/rst/java/cluster-sharding.rst index b5caa18af8..ad200770dd 100644 --- a/akka-docs/rst/java/cluster-sharding.rst +++ b/akka-docs/rst/java/cluster-sharding.rst @@ -22,6 +22,9 @@ the sender to know the location of the destination actor. This is achieved by se the messages via a ``ShardRegion`` actor provided by this extension, which knows how 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. + An Example ---------- diff --git a/akka-docs/rst/java/cluster-singleton.rst b/akka-docs/rst/java/cluster-singleton.rst index be37285dfb..b99ce381d6 100644 --- a/akka-docs/rst/java/cluster-singleton.rst +++ b/akka-docs/rst/java/cluster-singleton.rst @@ -53,6 +53,9 @@ It's worth noting that messages can always be lost because of the distributed na As always, additional logic should be implemented in the singleton (acknowledgement) and in the client (retry) actors to ensure at-least-once message delivery. +The singleton instance will not run on members with status :ref:`WeaklyUp ` if that feature +is enabled. + Potential problems to be aware of --------------------------------- diff --git a/akka-docs/rst/java/cluster-usage.rst b/akka-docs/rst/java/cluster-usage.rst index 5033bf1917..f0cdbe40cb 100644 --- a/akka-docs/rst/java/cluster-usage.rst +++ b/akka-docs/rst/java/cluster-usage.rst @@ -169,6 +169,8 @@ leaving member will be shutdown after the leader has changed status of the membe automatically, but in case of network failures during this process it might still be necessary to set the node’s status to ``Down`` in order to complete the removal. +.. _weakly_up_java: + WeaklyUp Members ^^^^^^^^^^^^^^^^ @@ -176,7 +178,13 @@ If a node is ``unreachable`` then gossip convergence is not possible and therefo ``leader`` actions are also not possible. However, we still might want new nodes to join the cluster in this scenario. -With a configuration option you can allow this behavior:: +.. warning:: + + The WeaklyUp feature is marked as **“experimental”** as of its introduction in Akka 2.4.0. We will continue to + improve this feature based on our users’ feedback, which implies that while we try to keep incompatible + changes to a minimum the binary compatibility guarantee for maintenance releases does not apply this feature. + +This feature is disabled by default. With a configuration option you can allow this behavior:: akka.cluster.allow-weakly-up-members = on @@ -185,11 +193,17 @@ When ``allow-weakly-up-members`` is enabled and there is no gossip convergence, cluster. Once gossip convergence is reached, the leader will move ``WeaklyUp`` members to ``Up``. +You can subscribe to the ``WeaklyUp`` membership event to make use of the members that are +in this state, but you should be aware of that members on the other side of a network partition +have no knowledge about the existence of the new members. You should for example not count +``WeaklyUp`` members in quorum decisions. + .. warning:: This feature is only available from Akka 2.4.0 and cannot be used if some of your cluster members are running an older version of Akka. + .. _cluster_subscriber_java: Subscribe to Cluster Events @@ -458,6 +472,9 @@ automatically unregistered from the router. When new nodes join the cluster addi routees are added to the router, according to the configuration. Routees are also added when a node becomes reachable again, after having been unreachable. +Cluster aware routers make use of members with status :ref:`WeaklyUp ` if that feature +is enabled. + There are two distinct types of routers. * **Group - router that sends messages to the specified path using actor selection** diff --git a/akka-docs/rst/java/distributed-data.rst b/akka-docs/rst/java/distributed-data.rst index e9299ecb43..3bbf9869d5 100644 --- a/akka-docs/rst/java/distributed-data.rst +++ b/akka-docs/rst/java/distributed-data.rst @@ -30,7 +30,7 @@ out-of-date value. improve this API based on our users’ feedback, which implies that while we try to keep incompatible changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the contents of the ``akka.persistence`` package. - + Using the Replicator ==================== @@ -40,6 +40,10 @@ with a specific role. It communicates with other ``Replicator`` instances with t (without address) that are running on other nodes . For convenience it can be used with the ``akka.cluster.ddata.DistributedData`` extension. +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will currently not participate in Distributed Data, but that is something that should be possible to +add in a future release. + Below is an example of an actor that schedules tick messages to itself and for each tick adds or removes elements from a ``ORSet`` (observed-remove set). It also subscribes to changes of this. diff --git a/akka-docs/rst/java/distributed-pub-sub.rst b/akka-docs/rst/java/distributed-pub-sub.rst index f5a05ac721..6142daf8b6 100644 --- a/akka-docs/rst/java/distributed-pub-sub.rst +++ b/akka-docs/rst/java/distributed-pub-sub.rst @@ -79,6 +79,11 @@ Successful ``Subscribe`` and ``Unsubscribe`` is acknowledged with ``DistributedPubSubMediator.SubscribeAck`` and ``DistributedPubSubMediator.UnsubscribeAck`` replies. +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will participate in Distributed Publish Subscribe, i.e. subscribers on nodes with +``WeaklyUp`` status will receive published messages if the publisher and subscriber are on +same side of a network partition. + A Small Example --------------- diff --git a/akka-docs/rst/scala/cluster-metrics.rst b/akka-docs/rst/scala/cluster-metrics.rst index ff456c75f8..64cea2e988 100644 --- a/akka-docs/rst/scala/cluster-metrics.rst +++ b/akka-docs/rst/scala/cluster-metrics.rst @@ -29,6 +29,9 @@ and add the following configuration stanza to your ``application.conf`` Make sure to disable legacy metrics in akka-cluster: ``akka.cluster.metrics.enabled=off``, since it is still enabled in akka-cluster by default (for compatibility with past releases). +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will participate in Cluster Metrics collection and dissemination. + Metrics Collector ----------------- diff --git a/akka-docs/rst/scala/cluster-sharding.rst b/akka-docs/rst/scala/cluster-sharding.rst index 1f0f0b8957..4dff2f462a 100644 --- a/akka-docs/rst/scala/cluster-sharding.rst +++ b/akka-docs/rst/scala/cluster-sharding.rst @@ -22,6 +22,9 @@ the sender to know the location of the destination actor. This is achieved by se the messages via a ``ShardRegion`` actor provided by this extension, which knows how 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. + An Example ---------- diff --git a/akka-docs/rst/scala/cluster-singleton.rst b/akka-docs/rst/scala/cluster-singleton.rst index 4fae06ed17..c1631f5b5e 100644 --- a/akka-docs/rst/scala/cluster-singleton.rst +++ b/akka-docs/rst/scala/cluster-singleton.rst @@ -53,6 +53,9 @@ It's worth noting that messages can always be lost because of the distributed na As always, additional logic should be implemented in the singleton (acknowledgement) and in the client (retry) actors to ensure at-least-once message delivery. +The singleton instance will not run on members with status :ref:`WeaklyUp ` if that feature +is enabled. + Potential problems to be aware of --------------------------------- diff --git a/akka-docs/rst/scala/cluster-usage.rst b/akka-docs/rst/scala/cluster-usage.rst index 5adcc4c531..344dcde4ef 100644 --- a/akka-docs/rst/scala/cluster-usage.rst +++ b/akka-docs/rst/scala/cluster-usage.rst @@ -163,6 +163,8 @@ leaving member will be shutdown after the leader has changed status of the membe automatically, but in case of network failures during this process it might still be necessary to set the node’s status to ``Down`` in order to complete the removal. +.. _weakly_up_scala: + WeaklyUp Members ^^^^^^^^^^^^^^^^ @@ -170,7 +172,13 @@ If a node is ``unreachable`` then gossip convergence is not possible and therefo ``leader`` actions are also not possible. However, we still might want new nodes to join the cluster in this scenario. -With a configuration option you can allow this behavior:: +.. warning:: + + The WeaklyUp feature is marked as **“experimental”** as of its introduction in Akka 2.4.0. We will continue to + improve this feature based on our users’ feedback, which implies that while we try to keep incompatible + changes to a minimum the binary compatibility guarantee for maintenance releases does not apply this feature. + +This feature is disabled by default. With a configuration option you can allow this behavior:: akka.cluster.allow-weakly-up-members = on @@ -179,11 +187,17 @@ When ``allow-weakly-up-members`` is enabled and there is no gossip convergence, cluster. Once gossip convergence is reached, the leader will move ``WeaklyUp`` members to ``Up``. +You can subscribe to the ``WeaklyUp`` membership event to make use of the members that are +in this state, but you should be aware of that members on the other side of a network partition +have no knowledge about the existence of the new members. You should for example not count +``WeaklyUp`` members in quorum decisions. + .. warning:: This feature is only available from Akka 2.4.0 and cannot be used if some of your cluster members are running an older version of Akka. + .. _cluster_subscriber_scala: Subscribe to Cluster Events @@ -455,6 +469,9 @@ automatically unregistered from the router. When new nodes join the cluster, add routees are added to the router, according to the configuration. Routees are also added when a node becomes reachable again, after having been unreachable. +Cluster aware routers make use of members with status :ref:`WeaklyUp ` if that feature +is enabled. + There are two distinct types of routers. * **Group - router that sends messages to the specified path using actor selection** diff --git a/akka-docs/rst/scala/distributed-data.rst b/akka-docs/rst/scala/distributed-data.rst index 69d1f181f0..2686aeaad0 100644 --- a/akka-docs/rst/scala/distributed-data.rst +++ b/akka-docs/rst/scala/distributed-data.rst @@ -30,7 +30,7 @@ out-of-date value. improve this API based on our users’ feedback, which implies that while we try to keep incompatible changes to a minimum the binary compatibility guarantee for maintenance releases does not apply to the contents of the ``akka.persistence`` package. - + Using the Replicator ==================== @@ -40,6 +40,10 @@ with a specific role. It communicates with other ``Replicator`` instances with t (without address) that are running on other nodes . For convenience it can be used with the ``akka.cluster.ddata.DistributedData`` extension. +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will currently not participate in Distributed Data, but that is something that should be possible to +add in a future release. + Below is an example of an actor that schedules tick messages to itself and for each tick adds or removes elements from a ``ORSet`` (observed-remove set). It also subscribes to changes of this. diff --git a/akka-docs/rst/scala/distributed-pub-sub.rst b/akka-docs/rst/scala/distributed-pub-sub.rst index a7be9dd051..ac655e862d 100644 --- a/akka-docs/rst/scala/distributed-pub-sub.rst +++ b/akka-docs/rst/scala/distributed-pub-sub.rst @@ -79,6 +79,11 @@ Successful ``Subscribe`` and ``Unsubscribe`` is acknowledged with ``DistributedPubSubMediator.SubscribeAck`` and ``DistributedPubSubMediator.UnsubscribeAck`` replies. +Cluster members with status :ref:`WeaklyUp `, if that feature is enabled, +will participate in Distributed Publish Subscribe, i.e. subscribers on nodes with +``WeaklyUp`` status will receive published messages if the publisher and subscriber are on +same side of a network partition. + A Small Example ---------------