Akka.Cluster.Sharding Commands
The Akka.Cluster.Sharding commands supported by Petabridge.Cmd.Host
can be added to your Petabridge.Cmd.Host
installation by installing the Petabridge.Cmd.Cluster.Sharding
NuGet package:
PM> Install-Package Petabridge.Cmd.Cluster.Sharding
And then inside your Akka.NET application, you can simply register the ClusterShardingCommands
command palette with your ActorSystem
using the following syntax:
var cmd = PetabridgeCmd.Get(a);
cmd.RegisterCommandPalette(ClusterCommands.Instance);
cmd.RegisterCommandPalette(ClusterShardingCommands.Instance);
cmd.Start();
Known Limitations of Petabridge.Cmd.Cluster.Sharding
In order for any of the below commands to be effective, they must be executed on the node that hosts one of the ShardRegion
s for a given entity type, which means that the ActorSystem
Petabridge.Cmd.Host is running on should be one of the nodes in your cluster that is responsible for creating and starting entity actors.
If you need more information, please take a look at this technical overview of Akka.Cluster.Sharding in Akka.NET.
Available Commands
Command Name | Description |
---|---|
cluster-sharding regions |
Lists all Akka.Cluster.Sharding regions known to the current node. |
cluster-sharding region-addr |
List the Akka.Cluster members that are currently hosting a shard in the specified region. |
cluster-sharding region-stats |
Get statistics for the provided shard region across all nodes. |
cluster-sharding local-stats |
Get statistics for the provided shard region for only the current node. |
cluster-sharding locate-entity |
Used to query the location of entity actors throughout a given ShardRegion . |
cluster-sharding regions
cluster-sharding regions
can be used to query all of the regions that are known to the current node, usually 1 per entity type.
If there are regions hosted on other nodes, but not the node the pbm
client is currently connected to, those regions will not be listed by this command.
cluster-sharding regions
doesn't take any commandline arguments.
Examples
Listing regions hosted on the current node.
pbm [host:port] cluster-sharding regions.
cluster-sharding region-addr
cluster-sharding region-addr
can be used to list all of the nodes that are hosting a specific named ShardRegion
supplied in the arguments for this command, provided that the current node is one of the hosts for this region.
cluster-sharding region-addr
takes the following arguments:
Argument Name | Switches | Mandatory? | Allow Multiple? | Is Flag? | Description |
---|---|---|---|---|---|
region | -r or -R | yes | no | no | The name of the shard region we want to query. |
Examples
Listing the addresses of all nodes hosting the ShardRegion
called region-name
.
pbm [host:port] cluster-sharding region-addr -r [region-name].
cluster-sharding region-stats
cluster-sharding region-stats
can be used to list all of the nodes and their sharding statistics that are hosting a specific named ShardRegion
supplied in the arguments for this command, provided that the current node is one of the hosts for this region.
cluster-sharding region-stats
takes the following arguments:
Argument Name | Switches | Mandatory? | Allow Multiple? | Is Flag? | Description |
---|---|---|---|---|---|
region | -r or -R | yes | no | no | The name of the shard region we want to query. |
verbose | -v or -V | no | no | yes | When this flag is turned on, in addition to printing shard statistics for each node, the command will also list all of the shardIds and the number of entities per-shard on each node. Off by default. |
Examples
Listing the addresses and statistics of all nodes hosting the ShardRegion
called region-name
.
pbm [host:port] cluster-sharding region-stats -r [region-name].
cluster-sharding local-stats
cluster-sharding local-stats
can be used to list the current node's sharding statistics for the specific named ShardRegion
supplied in the arguments for this command, provided that the current node is one of the hosts for this region.
cluster-sharding local-stats
takes the following arguments:
Argument Name | Switches | Mandatory? | Allow Multiple? | Is Flag? | Description |
---|---|---|---|---|---|
region | -r or -R | yes | no | no | The name of the shard region we want to query. |
Examples
Listing the statistics of the current node hosting the ShardRegion
called region-name
.
pbm [host:port] cluster-sharding local-stats -r [region-name].
cluster-sharding locate-entity
cluster-sharding locate-entity
can be used to query a specific entity within a given ShardRegion
- the response will show whether or not this entity is live inside the cluster and on which node it would be located.
cluster-sharding locate-entity
has the following arguments:
Argument Name | Switches | Mandatory? | Allow Multiple? | Is Flag? | Description |
---|---|---|---|---|---|
region | -r or -R | yes | no | no | The name of the shard region we want to query. |
entityId | -e or -E | yes | yes | no | The ids of the entities we want to query. |
Important
This command will not work properly if your ShardRegion
's IShardExtractor
does not support the ShardRegion.StartEntity
message - which is also required in order to ensure that remember-entities=on
works properly inside Cluster.Sharding. You will see warning messages about this from pbm
if it consistently fails to resolve sharded entities. See "Akka.Cluster.Sharding: Querying for the Location of Specific Entities" for specifics.
Examples
Querying entities with ids "1" and "2" inside a ShardRegion
with type "entity":
cluster-sharding locate-entity -r entity -e 1 -e 2