Skip to main content
The metrics family enables the Metrics role, reports its status, selects exporter Nodes, shows the Grafana credential, and disables the role. The Metrics reference explains what the role runs, which Nodes it selects, and who may open Grafana.

​
Commands

Every command accepts --json. A node argument is a numeric Node ID or a Node name. Every command needs exactly one active Gateway Node. The caller must be the Gateway Node or hold an access grant to it. Otherwise the command fails with node_access.required.

​
orbit metrics:enable

Enable the Metrics role on one active Node.
A second enable fails with node.role_conflict. Retry a failed convergence with orbit node:role:add <node> metrics --converge.

​
orbit metrics:status

Show whether Metrics is enabled and the Grafana URL. The output also shows the assignment with its Node, status, failed step, and error code, plus the Metrics reconcile status and error code. It has one row per exporter with its desired state, actual state, selection reason, degraded reason, and degraded error code.

​
orbit metrics:credentials

Show the verified Grafana administrator credential, or reset the password.
Human output prints the URL, the user admin, the password, and the request ID. A concurrent read or reset waits. It then reads the result or fails with metrics.credentials_busy and changes nothing.

​
orbit metrics:exporter:enable

Store an enabled exporter preference for one Node.
The command fails with metrics.exporter_node_inactive for a Node that is not active. It fails with metrics.exporter_node_ineligible for a Node that the Gateway does not manage over SSH. It checks both before it stores the preference.

​
orbit metrics:exporter:disable

Store a disabled exporter preference for one Node.
The command fails with metrics.exporter_node_inactive for a Node that is not active. It fails with node.role_conflict for the Metrics Node.

​
orbit metrics:disable

Disable the Metrics role. The data stays unless you purge it.
In a terminal, the command shows a preview and asks for confirmation. The default answer is No. A decline, Ctrl-C, or EOF fails with input.cancelled and changes nothing. Without --force, a call that cannot prompt fails with metrics.force_required. --purge-data without --force fails the same way in every mode. The result reports publication as cleaned or uncleaned. For uncleaned, the command prints a warning: the metrics.orbit site, certificate, and DNS record stay on the Gateway. Disable and purge lists what the command removes and what it keeps.
  • node retries a failed convergence with node:role:add <node> metrics --converge, relocates the role, and removes it with node:role:remove.
  • doctor checks the exporter firewall rules on selected Nodes.
  • firewall adds operator rules beside the role’s orbit: rules.