xOneRS ships a Docker Compose file, ops/grafana/docker-compose.yml, that starts Prometheus, Grafana and node_exporter for one node, with the "xOne overview" dashboard and the alert rules already loaded. An Alertmanager is optional. Every port binds to 127.0.0.1, and Grafana has no default password: you write one to a file first. The steps below come from docs/ops/monitoring.md.

What the metrics mean and how to tune the rules is in ten Prometheus series to alert on and alert tuning.

What does the compose file start?

REFERENCE TABLEScroll to explore all columns →
Service Image Port Notes
prometheus prom/prometheus:v2.53.0 127.0.0.1:9090 loads ops/prometheus/prometheus.yml, targets/ and alerts.yml; data in the prometheus-data volume
node-exporter prom/node-exporter:v1.8.2 none published read-only view of the host root, for the disk alerts
grafana grafana/grafana:11.1.0 127.0.0.1:3000 dashboard "xOne overview" provisioned; sign-up and anonymous access off; data in grafana-data
alertmanager prom/alertmanager:v0.28.1 127.0.0.1:9093 only with --profile alerts; delivers nothing until you choose a receiver in ops/alertmanager/alertmanager.yml

Prometheus keeps at most PROMETHEUS_RETENTION_TIME (default 15d) and PROMETHEUS_RETENTION_SIZE (default 5GB) of samples, whichever limit comes first (docker-compose.yml).

How do I start it?

  1. Start the node with metrics on an address the containers can reach: --metrics --metrics.addr 0.0.0.0. The default port is 6060. With 0.0.0.0 the metrics port listens on every interface of the host, so limit it with your host firewall.
  2. If the node does not listen on host.docker.internal:6060, set the target in ops/prometheus/prometheus.yml.
  3. Write a Grafana admin password to a file only you can read:
install -m 600 /dev/null ops/grafana/grafana_admin_password
openssl rand -base64 24 > ops/grafana/grafana_admin_password
docker compose -f ops/grafana/docker-compose.yml up -d
  1. Open Grafana on http://127.0.0.1:3000 as admin with that password. The alerts page of Prometheus is http://127.0.0.1:9090/alerts.

Without the password file, docker compose up stops with "secret file not found". To add the Alertmanager, start with --profile alerts.

How do I check that it works?

Run ops/check-monitoring.py [--node HOST:PORT] [--prometheus URL] [--job xone]. It passes only if the node serves /metrics with xone_head_block_number, Prometheus has an active xone target on the node's port that is up, and the head series has a sample, so the dashboard is not empty. It sends GET requests only and changes nothing.

Note one open item: five exported series (missed turns, timeouts, queue overflow, storage bytes, dropped log lines) read 0 on main today, so three shipped alert rules cannot fire yet. Issue #994 tracks it.

How do I reach it from another machine?

Keep both ports on loopback. Use an SSH tunnel (ssh -L 3000:127.0.0.1:3000 <host>) or an authenticated TLS reverse proxy. The doc says not to change the bindings to 0.0.0.0.

Can I monitor several nodes?

Yes. ops/prometheus/xone-targets.sh set <name> <host:port> [network] writes one target file per instance under ops/prometheus/targets/. Prometheus scrapes it with node and network labels without a restart. remove <name> stops it and list shows the targets. Targets are host:port only, so no credential reaches a label.

What survives an upgrade?

The prometheus-data and grafana-data volumes. docker compose pull && docker compose up -d keeps the dashboards, the recent metrics and the Grafana password. Only docker compose down -v deletes them. Grafana reads the password file only on its first start; change the password later in the Grafana UI or with docker compose exec grafana grafana cli admin reset-admin-password <new>.

How do other clients describe this?

REFERENCE TABLEScroll to explore all columns →
Client What its documentation states xOne
reth --metrics 127.0.0.1:9001 and a shipped Grafana dashboard, as stated in reth monitoring a shipped dashboard and a compose stack; metrics on port 6060 by default
besu --metrics-enabled, port 9545, Grafana dashboard 16455, as stated in Besu metrics --metrics, --metrics.addr, --metrics.port
nethermind a docker compose of Prometheus, Grafana and a push gateway in NethermindEth/metrics-infrastructure, as stated in Nethermind Grafana and Prometheus pull only; no push gateway in the stack

Frequently asked questions

What is the default Grafana password of the xOne stack?

There is none. You write one to ops/grafana/grafana_admin_password before the first start; without it the stack does not start.

Which ports does the stack open?

Grafana on 127.0.0.1:3000, Prometheus on 127.0.0.1:9090, and the optional Alertmanager on 127.0.0.1:9093. All bind to loopback.

Do I need the Alertmanager?

Only if you want notifications. Start it with --profile alerts and choose a receiver in ops/alertmanager/alertmanager.yml; until then it delivers nothing.

How do I know the dashboard has data?

Run ops/check-monitoring.py. It exits 0 only when the node, the Prometheus target and the head series all check out.

Sources