Monitor cluster status#

Starburst control plane checks the status of each cluster at a regular interval, and shows the status in the Clusters pane. The default interval is 30 seconds. See Status check interval.

Status values#

Status

Meaning

PENDING

The cluster is starting up. A cluster that you add also starts as PENDING, and it becomes HEALTHY only after it passes the checks.

HEALTHY

The cluster is ready and available. Control plane includes only healthy clusters in its routing decisions.

UNHEALTHY

The cluster failed health checks, or the Shared secret does not match the internal-communication.shared-secret of the cluster. See Shared secrets.

UNKNOWN

Control plane cannot communicate with the cluster. Possible reasons include the cluster going offline or a typo in the cluster URL.

UNSUPPORTED

The cluster is not a supported SEP cluster. Control plane does not send queries to it.

When a cluster is unsupported#

Control plane reports the status UNSUPPORTED in any of the following cases:

  • The cluster does not have an Elite SEP license.

  • The cluster runs a SEP version earlier than 480-e.

  • The coordinator of the cluster does not expose the metrics that control plane requires for monitoring, which typically happens with older SEP versions.

  • The cluster name is invalid, which can happen if you added the cluster before internal communication monitoring was supported.

  • The node.environment property of the coordinator does not match the cluster name that you use in control plane.

  • Control plane runs in managed mode (control-plane.enabled=true), and the cluster does not. The reason is DEPLOYMENT_MODE_NOT_MANAGED. This happens if the deployment.mode property of the cluster is not MANAGED, or if the cluster runs a SEP version earlier than 2026.6.0, which does not report its mode. Set deployment.mode=MANAGED and deployment.manager.uri in the configuration of the cluster, and upgrade the cluster if it runs an earlier version. See Connect a cluster to control plane.

  • The secret that is stored for the cluster is broken, and control plane cannot decrypt it.

  • Control plane runs in managed mode, and you registered the cluster with a fixed URL, in the Proxy to field. The reason is DISCOVERY_REQUIRED. Edit the cluster, and turn on Use discovery. See Discovery in managed mode.

Status check interval#

Control plane checks each cluster every time the interval passes. A change in a cluster shows in its status after the next check.

Property

Description

Default

gateway.clusters.monitoring.refresh-interval

Interval between health check requests to registered clusters. Lower values provide faster detection of cluster failures but increase network traffic. The minimum is 1s.

30s

View the metrics of a cluster#

  1. In the Clusters pane, open the more_vert options menu of the cluster, and select View metrics.

  2. Read the status and the summary of the cluster at the top of the page.

  3. Select a time range. The charts show CPU, memory, queries, and workers. The charts of the recent ranges update automatically.

  4. To keep the data, click Download to save it as a CSV file.

You need permission to read the cluster. If the history of the cluster is not available, the page shows an error.