Actors/Packages/CLI
@sigx/actors-cli · Preview

CLI#

A sigx CLI plugin for observing actors: hosts, latency, errors and cluster topology, from a terminal.

v0.11.0 MIT

Installation#

Terminal 
pnpm add -D @sigx/actors-cli
Terminal 
sigx actors                                        # the dashboard
sigx actors top --url http://host:7311             # …against a running host
sigx actors stats --json | jq '.cluster.totals'    # a snapshot, for piping
sigx actors health --url http://host:7311          # exit code by readiness

Requires @sigx/cli ≥ 0.9 and @sigx/terminal ≥ 0.11. On older versions the plugin's version guard warns and the dashboard never learns its pane size.

Two ways to reach a host#

Embedded (the default) loads your project's actor app module in-process and reads it directly. Zero config, no secret, and it sees strictly more than the wire can — full latency histograms, the whole activation list, the cluster placement itself.

It also starts a host. That host is real: it joins membership, claims actors and ticks reminders. Fine pointed at a dev app, wrong pointed at production.

HTTP (--url) polls a running host's ops() endpoint. It loads no user code and holds no host, so it is the mode for anything you did not just start yourself. --url wins over a local module.

The same five tabs, in a browser#

The dashboard's five tabs — Overview, Hosts, Actors, Cluster, Health — draw the data layer in @sigx/actors-monitor, and @sigx/actors-dashboard draws the same layer in a browser as embeddable sigx components. One data layer, two renderers: the numbers agree because neither derives them.

What each mode needs#

The sigx binary discovers plugins from the dependencies of the project you run it in — it reads ./package.json and looks for a sigx-cli field in each dependency's manifest. So sigx actors is available in any directory whose project lists @sigx/actors-cli in its dependencies or devDependencies. Beyond that, the two modes need different things:

  • HTTP needs only @sigx/actors-cli, a --url and the ops secret (SIGX_OPS_SECRET). It works from a project that has no @sigx/actors dependency at all — an ops box, a control plane watching several clusters, a CI probe — because it loads no user code.
  • Embedded needs a project that depends on @sigx/actors, since it loads that project's app module. Without --url in a project that does not, the command exits with code 2:
$ sigx actors top
[sigx actors] embedded mode needs a project that depends on @sigx/actors; pass --url <origin> to watch a running host instead.

In a monorepo, run embedded mode from the package that owns the host:

Terminal 
pnpm --filter my-app exec sigx actors top

Next steps#