Petabridge.Cmd.Host 1.4.0

Petabridge.Cmd

Petabridge.Cmd is a command-line interface (CLI) for Akka.NET, designed to help monitor and manage live ActorSystems through simple commands.

• Website: https://cmd.petabridge.com/
• Chat: 🗣️ https://discord.gg/kgsruUF889
• Issue Tracker: 🪲 https://github.com/petabridge/petabridge.cmd-issues

Use

After you've installed the Petabridge.Cmd.Host into your Akka.NET application and the pbm client onto your workstation, you can connect to your server, download any commands that are defined on them, and begin executing them right away!

Some examples:

Print Current Actor Hierarchy

pbm actor hierarchy

Print Current Cluster Status

Only works when Petabridge.Cmd.Cluster is installed.

pbm cluster show

Down All Unreachable Nodes in Cluster

Only works when Petabridge.Cmd.Cluster is installed.

pbm cluster down-unreachable

There are dozens of built-in Petabridge.Cmd commands and it's quite easy to build your own custom ones!

Installation

In order to use Petabridge.Cmd you must follow our installation instructions and get both a server and a client up and running.

Default Ports and Hostnames

By default, Petabridge.Cmd.Host will open the following ports for accepting TCP connections from pbm clients:

• Port: 9110
• Host: All addresses (0.0.0.0)

Server and Command Pallette Installation

Before we can use the Petabridge.Cmd client (pbm) we need to install the Petabridge.Cmd server inside one of our Akka.NET applications - which we can do by installing the Petabridge.Cmd.Host NuGet package:

dotnet add package Petabridge.Cmd.Host

Next, we just need to hook this up into our ActorSystem.

Using Akka.Hosting (Recommended)

Akka.Hosting is a HOCON-less approach to configuring and instantiating Akka.NET applications, and it's the easiest way to configure Petabridge.Cmd inside your ActorSystem - using the AddPetabridgeCmd method found in the Petabridge.Cmd.Host package:

using var host = await (new HostBuilder().ConfigureServices((context, collection) =>
{
    collection.AddAkka("PbmSys", builder =>
    {
        builder.WithRemoting("localhost", 29909)
            .WithClustering(new ClusterOptions(){ SeedNodes = new[]{ "akka.tcp://PbmSys@localhost:29909" }})
        .AddPetabridgeCmd(
                new PetabridgeCmdOptions(){ Host = "localhost", Port = 8222}, // optional - customize pbm bindings 
                cmd =>
        {
            cmd.RegisterCommandPalette(new RemoteCommands());
            cmd.RegisterCommandPalette(ClusterCommands.Instance);
        });
    });
}).StartAsync());

You can register all of your CommandPalette instances using the builder and Petabridge.Cmd will be started up automatically. All HOCON values can still be used to configure binding addresses.

Manually Starting Petabridge.Cmd

In order to active Petabridge.Cmd.Host inside your Akka.NET application, you need to make the following call inside your application (if you're not using Akka.Hosting:)

private static void Main(string[] args)
{
    using (var a = ActorSystem.Create("Foo"))
    {
        var cmd = PetabridgeCmd.Get(a);
        cmd.Start();
        a.WhenTerminated.Wait();
    }
}

Registering Additional Command Palettes

See the full set of built-in Petabridge.Cmd palettes here.

Petabridge.Cmd ships with an additional set of commands for managing Akka.Cluster applications, which are not loaded by default. After installing the Petabridge.Cmd.Cluster NuGet package into your host application, you an register the commands with the PetabridgeCmd plugin via the following syntax:

using (var a = ActorSystem.Create("webcrawler"))
{
    var cmd = PetabridgeCmd.Get(a);
    cmd.RegisterCommandPalette(ClusterCommands.Instance); // non-default command palette
    cmd.Start();
    a.WhenTerminated.Wait();
}

Or when using Akka.Hosting:

collection.AddAkka("PbmSys", builder =>
{
    builder.WithRemoting("localhost", 29909)
        .WithClustering(new ClusterOptions(){ SeedNodes = new[]{ "akka.tcp://PbmSys@localhost:29909" }})
    .AddPetabridgeCmd(
            new PetabridgeCmdOptions(){ Host = "localhost", Port = 8222}, // optional - customize pbm bindings 
            cmd =>
    {
        cmd.RegisterCommandPalette(new RemoteCommands());
        cmd.RegisterCommandPalette(ClusterCommands.Instance); // non-default command palette
    });
});

Client Installation

The easiest way to install Petabridge.Cmd's client is to install the pbm .NET global tool:

> dotnet tool install --global pbm 

To see full details about how the Petabridge.Cmd client and server connectivity model works, please see "How Petabridge.Cmd Works."

Need Help?

To get help with Petabridge.Cmd you can file a bug on our issue tracker or contact us in Discord.