> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-gateway/5/monitor-cluster-health-activity/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# Monitor gateway cluster health and activity

Gateway 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](./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](/itential-platform/studio/workflows/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.

```bash
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:

```bash
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](./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.

```bash
iagctl inspect cluster activity
```

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

Example output:

```bash
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](./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.

```bash
iagctl inspect cluster
```

For more information, see [iagctl inspect cluster](./iagctl/inspect-cluster).