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 ShardRegions 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