Actor Commands

Petabridge.Cmd.Host contains a set of commands designed to help Akka.NET users visualize their actor hierarchies and acquire other important pieces of information about the state of their actors.

Available Commands

Command Name Description
`actor hierarchy`

Prints the actor hierarchy from a given starting position all the way down to a specified level of depth.

Warning: output can be quite long for large actor hierarchies.
`actor system` Gets the full name and address of the currently connected `ActorSystem`.
`actor ping` Queries a specific actor at a given `ActorPath` to see if it exists and is responsive.
`actor stop` Kills a local or remote actor using the given path. This will kill an actor using a `PoisonPill`.
`actor alive` Lists all living actors grouped by type, with optional filtering. Requires Akka.NET telemetry to be enabled.

actor hierarchy

A useful tool in the course of managing or debugging an Akka.NET application is the ability to visualize what the current state of an actor hierarchy looks like. You can see how many children a particular actor has, what they're named, whether they're remotely deployed or not, and so forth.

actor hierarchy takes the following arguments:

Argument Name Switches Mandatory? Allow Multiple? Is Flag? Description
start -s or -S no no no The starting actor path to use in the query; everything in the trace will traverse the actor hierarchy from this point onward. Defaults to `akka://{ActorSystem}/user/` if left blank. Can also be a remote `ActorPath` if Akka.Remote is used.
depth -d or -D no no no The depth in the actor hierarchy to query. A depth of 1 means that only children of the starting actor are queried. Depth of 2 means that grandchildren are queried. And so forth. Defaults to `2`.
timeout-per-layer -t or -T no no no The time in milliseconds given to collect actor's responses to `ActorIdentity` message on each layer of the hierarchy. Defaults to `40`.
exclude-system-actors -e or -E no no yes When set, this query will exlcude all actors from the `/system` portion of the actor hierarchy.

Examples

Querying the top-level actors of the current actor hierarchy.

pbm [host@port] actor hierarchy -d 1

Querying the actor hierarchy up to 6 layers deep and exporting the results to a file (Windows.) Uses "single shot" mode of pbm.

C:\> pbm [host@port] actor hierarchy -d 6 > actor-hierarchy.txt

Querying a non-root actor's children.

pbm [host@port] actor hierarchy -s /user/foo/child1 -d 1

Querying the actor hierarchy up to 6 layers deep with timeout per layer increased up to 400ms

pbm [host@port] actor hierarchy -d 6 -t 400

Querying the actor hierarchy minus any /system actors.

pbm [host@port] actor hierarchy -e
Note

If you get inconsistent results when running actor hierarchy command (i.e. some actors are not displayed in the output from time to time), try to expand the timeout parameter value.

actor system

Prints the fully qualified name of the ActorSystem of the current Petabridge.Cmd.Host, including any inbound Akka.Remote listening information.

actor system takes no arguments.

Examples

Query the name of the current ActorSystem.

pbm [host:port] actor system

actor ping

Pings a local or remote actor using the given path. Used to validate that a given actor is both alive and responsive.

Argument Name Switches Mandatory? Allow Multiple? Is Flag? Description
start -p or -P yes no no The `ActorPath` to ping, i.e. `/user/foo` to query. Can also be a remote `ActorPath` such as `akka.tcp://MySys@localhost:12030/user/foo`.
timeout -t or -T no no no The timeout for the ping query in milliseconds. Defaults to `100` ms.

Examples

Query a local actor at /user/blackhole.

pbm [host:port] actor ping -p /user/blackhole

Query a remote actor running on akka.tcp://MySys@localhost:14420

pbm [host:port] actor ping -p akka.tcp://MySys@localhost:14420/user/blackhole

actor stop

Kills a local or remote actor using the given path. This will kill an actor using a PoisonPill.

Argument Name Switches Mandatory? Allow Multiple? Is Flag? Description
start -p or -P yes no no The `ActorPath` i.e. `/user/foo` to terminate. Can also be a remote `ActorPath` such as `akka.tcp://MySys@localhost:12030/user/foo`.
timeout -t or -T no no no The maximum wait time to confirm that an actor has been terminated. Defaults to `2000` ms.

Examples

Terminate a local actor at /user/blackhole.

pbm [host:port] actor stop -p /user/blackhole

Terminate a remote actor running on akka.tcp://MySys@localhost:14420

pbm [host:port] actor stop -p akka.tcp://MySys@localhost:14420/user/blackhole

actor alive

Lists all living actors grouped by type with their current counts. This command is useful for monitoring actor lifecycle and detecting potential memory leaks or actor proliferation issues.

Important

This command requires Akka.NET telemetry to be enabled in your ActorSystem configuration:

akka.actor.telemetry.enabled = on

This command also depends on events emitted by actors as they are being started and stopped. In order for it to accurately reflect the current state of living actors, you will need to start Petabridge.Cmd as soon as the ActorSystem is started.

See Prerequisites below for additional configuration methods.

Argument Name Switches Mandatory? Allow Multiple? Is Flag? Description
type -t or -T no yes no Filter results by actor type name (supports partial matching). If not specified, all actor types are shown.

Prerequisites

To use actor alive, enable telemetry in your ActorSystem; you will also need to start Petabridge.Cmd as soon as the ActorSystem is started.

HOCON Configuration:

akka.actor.telemetry.enabled = on

Akka.Hosting:

services.AddAkka("MyActorSystem", (builder, sp) =>
{
    builder.AddHocon("akka.actor.telemetry.enabled = on", HoconAddMode.Prepend);
    builder.AddPetabridgeCmd( // start Petabridge.Cmd as soon as possible
        new PetabridgeCmdOptions(){ Host = "localhost", Port = 8222},  
        cmd =>
        {
            cmd.RegisterCommandPalette(new RemoteCommands());
            cmd.RegisterCommandPalette(ClusterCommands.Instance);
        });
});

Classic API:

var config = ConfigurationFactory.ParseString("akka.actor.telemetry.enabled = on");
var system = ActorSystem.Create("MyActorSystem", config);
PetabridgeCmd.Get(system).Start(); // start Petabridge.Cmd as soon as possible

Examples

List all living actors grouped by type:

pbm [host:port] actor alive

Filter to show only actors with "Worker" in their type name:

pbm [host:port] actor alive -t Worker

Filter to show multiple actor types:

pbm [host:port] actor alive -t Worker -t Manager

Sample Output

PingActorOne | Petabridge.Cmd.Host.Sample.PingActorOne | 3
PingActorTwo | Petabridge.Cmd.Host.Sample.PingActorTwo | 5
WorkerActor | MyApp.Actors.WorkerActor | 12

Each line shows:

  • Short type name or the actor type override name, if it is overridden
  • Full type name (namespace.classname)
  • Current count of living actors of that type