Monitor gateway cluster health and activity

IAG 5.4+

Use the iagctl inspect cluster commands to monitor the live state of a gateway cluster. These commands give you visibility into cluster health and active execution before you perform maintenance tasks like taking a runner node offline, restarting a service, or making configuration changes.

To view gateway cluster details, admin state, certificates, and service groups in the Gateway Manager UI, see View gateway cluster details.

Cluster health and activity can also be checked directly from a workflow using the Inspect Cluster task from the GatewayManager collection in the task palette. For more information on adding tasks to workflows, see Create and run workflows.

Check cluster health

Run iagctl inspect cluster health to verify that the gateway cluster’s backing datastore is reachable and that at least one runner node is responding. Use this command before performing maintenance to confirm the gateway cluster is in a known good state, or after a change to verify the cluster recovered as expected.

$ iagctl inspect cluster health

The command checks the following:

Whether the gateway store is reachable
Whether each registered runner node is responding

The command exits with code 0 when the cluster is healthy and a non-zero code when unhealthy, with no output parsing required.

Example output:

$ Cluster:          test_cluster
$ Store:            local (healthy)
$ Runners:          1 registered, 1 reachable
$ Gateway Manager:  connected
$ 
$ COMPONENT         TYPE               ADDRESS                                   STATUS
$ store             local              /Users/test/.gateway.d/gateway.db         ● healthy
$ runner            embedded           localhost:50051                           ● reachable
$ gateway-manager   wss                localhost:8080                            ● connected
$ controller        —                  test-dev (this node)                      ● active

For full output field descriptions, see iagctl inspect cluster health.

Check cluster activity

Run iagctl inspect cluster activity to see all currently running and recently completed work across every runner node in the cluster. Use this command to confirm that no services are actively executing before taking a runner node offline or restarting the gateway cluster.

$ iagctl inspect cluster activity

The command fans out to all registered runners simultaneously and returns a combined view of execution activity.

Example output:

$ NAME         TYPE               STATUS        NODE                STARTED (UTC)   COMPLETED (UTC)   DURATION
$ test-plybk   ansible-playbook   ~ running     123.45.0.10:50051   20:24:12.243.   -                 1m35.382s
$ test-python  python-script      ○ failed      123.45.0.10:50051   20:22:14.959    20:22:14.974      16ms
$ 19d3683...   runCode            ● succeeded   123.45.0.8:50051    20:10:53.917    20:10:59.767      5.85s
$ f1b7a2e...   runCode            ● succeeded   123.45.0.10:50051   20:10:01.560    20:10:07.541      5.981s

Recently completed work is retained in the activity output for up to 15 minutes after completion. After that window, entries no longer appear.

For full output field descriptions, see iagctl inspect cluster activity.

Run both checks together

Run iagctl inspect cluster without a subcommand to display health and activity output together in a single call.

$ iagctl inspect cluster

For more information, see iagctl inspect cluster.