Petabridge has been working with Akka.NET users since January, 2015 and one of the biggest gaps in the Akka.NET ecosystem thus far has been adequate tooling for deployment, monitoring, and management of Akka.NET applications. This has been especially true for users who are building sophisticated, high-performance distributed systems using Akka.Cluster.

Today we’re pleased to announce the release of the first one of our tools for this purpose: Petabridge.Cmd - a command-line interface for managing Akka.NET applications in production.

Petabridge.Cmd Features

So what can Petabridge.Cmd do? Out of the box, it supports the following:

1. Akka.Cluster management - view the status of the cluster, down nodes, trigger nodes to leave the cluster gracefully, and have new nodes join an existing cluster;
2. Akka.NET log management - perform a live tail of logs from a given node, view historical logs, manually append log messages, and more;
3. Akka.NET actor hierarchy visualization - perform a live trace of the current actor hierarchy, including ones on remote machines;
4. System information - view data about the uptime of the current node and etc;
5. Ability to define custom, application-specific management commands, which can be automatically downloaded from the Petabridge.Cmd.Host server to the pbm client with no code updates necessary; and
6. Tab-autocomplete, help information, command memorization, argument hints, and a two-line installation process.

Petabridge.Cmd provides an out of the box experience that is designed to give most Akka.NET users 80% of what they need right out of the gate.

Installation

Petabridge.Cmd ships as two component parts which work together:

1. The pbm client, which can be installed via Chocolatey - a package manager for Windows and
2. The Petabridge.Cmd.Host, which is installed to your Akka.NET application via NuGet.

The Petabridge.Cmd installation guide provides more details, but here’s the short installation instructions.

After you’ve installed Chocolatey, install the pbm commandline agent via the following in a command or PowerShell window with administrator permissions:

PS> choco install petabridge-cmd

Next, open the application that you want to be able to manage using the pbm client and install the Petabridge.Cmd.Host NuGet package:

PM> Install-Package Petabridge.Cmd.Host

And then add the following lines of code to the area where you start your ActorSystem:

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

That’s it! When your Akka.NET application begins the Petabridge.Cmd.Host will be listening on 0.0.0.0:9110 by default and you can connect to it via the following:

PS> pbm 127.0.0.1:9110

If you want to configure Petabridge.Cmd to run on a different host port, make sure you read the Petabridge.Cmd.Host configuration guide.

How Petabridge.Cmd Works

As we mentioned in the installation section, Petabridge.Cmd works as two separate but connected parts: the pbm client and the Petabridge.Cmd.Host.

The pbm client is lightweight and can’t do much on its own; instead, it downloads the set of all available commands from the Petabridge.Cmd.Host and memorizes them. So long as the commands are defined using a compatible Petabridge.Cmd command syntax and scheme, the pbm client can learn them without ever having to be updated.

Therefore, this means that the available commands for a pbm client can vary by service and additional commands can be installed on a Petabridge.Cmd.Host as NuGet packages.

The pbm client can translate any CLI input into a Command that will be processed by the server, and in exchange the pbm client will receive a stream of CommandResponse objects whose output will be rendered onto the console.

You can learn more about the guts of Petabridge.Cmd here and you should really give the Petabridge.Cmd Quickstart tutorial a try if you’re interested in using it!

Best Practices

Some best practices to consider when using Petabridge.Cmd:

1. Petabridge.Cmd doesn’t need to be installed on every Akka.NET node - all you really need to manage an Akka.NET cluster with Petabridge.Cmd is to have the Petabridge.Cmd.Host installed on a handful of nodes; they can remotely manage the others.
2. For best results, install Petabridge.Cmd on your Akka.Cluster seed nodes - the next version of Lighthouse will ship with Petabridge.Cmd pre-installed already for this reason. Having Petabridge.Cmd installed on your seed nodes helps simplify deployment, network configuration, and more or less guarantees that at least one Petabridge.Cmd.Host will be connected to your cluster at all times.
3. Secure your Petabridge.Cmd endpoints via a private zone - you can read Petabridge.Cmd’s network security section for more details on why and how to do this.
4. Learn how to implement application-specific commands where helpful - check out the tutorial on creating custom Petabridge.Cmd Commands and the Petabridge.Cmd quickstart for examples.

And to all of our users: thank you for your valuable support and feedback. This tool is the brainchild of working with Petabridge customers for hundreds over hours over the past several years and we couldn’t have done it without you. Thank you!

If you have any suggestions, questions, or comments about Petabridge.Cmd (or anything else we’re cooking up) please leave a comment below!

Observe and Monitor Your Akka.NET Applications with Phobos

Did you know that Phobos can automatically instrument your Akka.NET applications with OpenTelemetry?

Click here to learn more.