> ## Documentation Index
> Fetch the complete documentation index at: https://orbit.nckrtl.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# metrics

> Enable the Prometheus and Grafana role on one Node, select which Nodes run an exporter, read the Grafana credential, and disable or purge the role.

The `metrics` family enables the Metrics role, reports its status, selects exporter Nodes, shows the Grafana credential, and disables the role. The [Metrics reference](/docs/reference/metrics) explains what the role runs, which Nodes it selects, and who may open Grafana.

## Commands

| Command | Result |
| - | - |
| [`metrics:enable`](#orbit-metricsenable) | Enable Metrics on one Node. |
| [`metrics:status`](#orbit-metricsstatus) | Show the assignment, container health, and exporter state. |
| [`metrics:credentials`](#orbit-metricscredentials) | Show or reset the verified Grafana administrator credential. |
| [`metrics:exporter:enable`](#orbit-metricsexporterenable) | Select one Node as an exporter. |
| [`metrics:exporter:disable`](#orbit-metricsexporterdisable) | Exclude one Node from exporter selection. |
| [`metrics:disable`](#orbit-metricsdisable) | Disable Metrics, and optionally delete its data. |

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.

```bash theme={"dark"}
orbit metrics:enable [node] [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `node` | when the command cannot prompt | Node ID or name. In a terminal, the command lists the active Nodes and asks. With `--json` or without a terminal, it fails with `metrics.node_required`. |

```bash theme={"dark"}
orbit metrics:enable beast
```

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.

```bash theme={"dark"}
orbit metrics:status [--json]
```

## orbit metrics:credentials

Show the verified Grafana administrator credential, or reset the password.

```bash theme={"dark"}
orbit metrics:credentials [--reset] [--json]
```

| Option | Meaning |
| - | - |
| `--reset` | Set a new password through Grafana's API, and return it after verification. |

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.

```bash theme={"dark"}
orbit metrics:exporter:enable <node> [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `node` | yes | Node ID or name. |

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.

```bash theme={"dark"}
orbit metrics:exporter:disable <node> [--json]
```

| Argument | Required | Meaning |
| - | - | - |
| `node` | yes | Node ID or name. |

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.

```bash theme={"dark"}
orbit metrics:disable [--force] [--purge-data] [--json]
```

| Option | Meaning |
| - | - |
| `--force` | Skip the confirmation. Required without a terminal, with `--json`, and with `--purge-data`. |
| `--purge-data` | Also delete the Prometheus and Grafana volumes and the stored Grafana passwords. |

```bash theme={"dark"}
orbit metrics:disable
orbit metrics:disable --force --purge-data
```

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](/docs/reference/metrics#disable-and-purge) lists what the command removes and what it keeps.

## Related

* [`node`](/docs/cli/node) retries a failed convergence with `node:role:add <node> metrics --converge`, relocates the role, and removes it with `node:role:remove`.
* [`doctor`](/docs/cli/doctor) checks the exporter firewall rules on selected Nodes.
* [`firewall`](/docs/cli/firewall) adds operator rules beside the role's `orbit:` rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.