XRPL Validator Linux Package Monitoring Guide

Revision: September 2026

Need monitoring credentials? If you do not have a Basic Auth username and password, request monitoring access before you start this guide.

Introduction

This guide explains how to connect an xrpld validator host to the XRPL monitoring platform with Grafana Alloy. You can use the guided installer or make the same changes yourself with the manual steps.

Still running rippled (pre-3.2.0)? rippled was renamed to xrpld in version 3.2.0. The installer detects legacy rippled nodes automatically: it also checks /etc/opt/ripple/rippled.cfg, /opt/ripple/etc/rippled.cfg, and /etc/rippled/rippled.cfg, the rippled systemd unit, and running rippled processes. Where this guide says xrpld.cfg or /var/log/xrpld/, use your existing rippled paths instead.

Opting in gives the validator operator access to validator health in Grafana. Metrics and logs make it easier to catch problems early, confirm that telemetry is flowing, and troubleshoot incidents without manually collecting log files after the fact.

The setup is designed to stay under the operator’s control. Alloy reads local telemetry and pushes it with credentials provided by the XRPL Foundation. The guided installer shows one focused preview before it offers to change xrpld.cfg. It asks separately before restarting xrpld, starting Alloy, or enabling Alloy. The manual path shows every command and file so you decide when to make each change.

The mental model is simple:

xrpld -> Grafana Alloy -> XRPL monitoring proxy -> Grafana

Grafana Alloy runs on the validator host. It reads local xrpld telemetry and pushes it to the monitoring platform:

  • StatsD metrics are collected.
  • Basic host CPU, memory, load, filesystem, disk, and network metrics can be enabled separately.
  • debug.log and perf.log are collected.
  • Grafana shows the validator dashboards.

The trusted validator identity is the Basic Auth username provided by the XRPL Foundation. The local node label is only a dashboard filter. Operators can optionally add the validator’s public master key to correlate the collector with public XRPL network statistics.

The guided installer is intentionally careful:

  • It shows complete affected xrpld.cfg telemetry sections with focused - and + changes.
  • It lets you apply the plan or open your editor in the same terminal.
  • It creates one protected original backup when a repair requires config changes and confirms its path before the action choice.
  • It asks separately before restarting xrpld.
  • It verifies the monitoring credentials before writing the final Alloy config.
  • It asks before starting or enabling Alloy.

Before You Start

What You Need

The XRPL Foundation provides:

  • Monitoring push host: push.monitoring.xrplf.org.
  • Grafana URL: https://monitoring.xrplf.org.
  • Basic Auth username and password.
  • Grafana account access.

The validator host needs:

  • systemd.
  • sudo, unless you work as root.
  • A readable xrpld.cfg.
  • Optionally, the validator’s public 52-character nH master key for correlation with public XRPL network statistics. This is not an account address, signing key, private key, or seed.
  • StatsD metrics, debug.log, and perf.log available from xrpld.
  • Outbound HTTPS access to push.monitoring.xrplf.org and Grafana’s package repository.

The current official XRPL package guides list these 64-bit x86 hosts:

  • Ubuntu 22.04 or 24.04, which receive the highest support and testing.
  • Debian 12 Bookworm, for which packages are available.
  • RHEL 9.6, which is supported.

See the XRPL system requirements, Ubuntu and Debian install guide, and RHEL install guide for current platform guidance. The steps below cover APT on Ubuntu or Debian and DNF or YUM on RHEL-family hosts.

Check The Monitoring Credentials

Check the username and password before storing them in the Alloy config. Replace <username> with the Basic Auth username from the XRPL Foundation:

curl --fail-with-body \
  --user '<username>' \
  https://push.monitoring.xrplf.org/health

curl asks for the password without displaying it. A successful check prints:

ok

An HTTP 401 means the username or password is wrong. An HTTP 403 means the credentials are valid but are not yet assigned to a monitoring tenant. Contact the XRPL Foundation if either error continues.

Choose A Setup Path

Both paths create the same Alloy setup and send the same telemetry.

  • Guided install: download the hosted installer, review it if you want, and answer each prompt. The installer explains each change before making it.
  • Manual install: run each command yourself, review the downloaded shared config, and create the small host-specific files by hand.

Use only one path. If you use the guided installer, continue with the next section. If you want to make every change yourself, skip to Manual Install.

Guided Install

Run The Installer

Use the hosted installer provided by the XRPL Foundation:

curl -fsSL https://push.monitoring.xrplf.org/alloy/install \
  | bash

To download and verify the installer before running it:

push_host="https://push.monitoring.xrplf.org"
install_sha256="fc8628d85953aa60a4859cd165ced7c791a938ec8cd58acab984b56aecf72f55"
installer="install-xrpl-monitoring.sh"
curl -fsSL "$push_host/alloy/install" -o "$installer"
printf '%s  %s\n' "$install_sha256" "$installer" | sha256sum -c -

sha256sum -c - must print OK. You can open the file in a text editor before you run it. When you are ready, run the same downloaded file:

bash "$installer"

What The Installer Does

The installer:

  1. Detects an existing Alloy package, service, and managed configuration.
  2. On a rerun, offers the actions allowed by the managed-version state: update an older installation, review the full setup, replace credentials on a current installation, or exit.
  3. Detects the OS and checks prerequisites.
  4. Asks for the push host, username, and password on a first install.
  5. Checks the credentials before installing Alloy or changing xrpld.cfg.
  6. Installs Grafana Alloy from the official Grafana package repository.
  7. Finds xrpld.cfg.
  8. Checks StatsD, debug.log, perf.log, and required log directories.
  9. Creates one original backup before the action choice when xrpld.cfg needs changes.
  10. Shows one repair plan with complete affected sections when xrpld.cfg needs telemetry changes.
  11. Lets you apply the plan or open the file in your editor without creating more backups.
  12. Before it automatically applies a StatsD relay change, stores a protected pending-state record that can be recovered after a paused run.
  13. Asks separately before restarting xrpld, then checks its log files.
  14. Checks Alloy’s read access to the logs.
  15. Asks for a node label and optional validator public master key.
  16. Asks whether to enable basic host metrics. The default answer is no.
  17. Writes and validates the Alloy config.
  18. Asks before starting or restarting Alloy and before enabling it at boot.
  19. Offers to redact plaintext push passwords from legacy config backups after Alloy starts.

On a first install, push.monitoring.xrplf.org is the default push host. Press Enter to use it, or enter another host. If curl is missing, the installer asks before installing that minimum prerequisite. No other package or node configuration change occurs before the credential check succeeds.

An older managed configuration can be updated without a full setup review. The installer loads the host and username from the managed config. It loads the password from /etc/alloy/xrpl-push, or from the managed config during a legacy migration. It keeps the password hidden, validates the credentials, and preserves existing redaction expressions. A version 5 config is updated with host metrics disabled. Use the full setup review to enable or disable them. It also migrates the unchanged StatsD mapping to its independent mapping version. If Alloy is running, the installer validates the update candidate and asks before it changes the managed files and restarts the service. After Alloy starts, the installer offers to replace a plaintext password in each legacy config backup with "<redacted>". The accepted action keeps the backup, writes the redaction atomically, and sets mode 0600.

An outdated installation must be updated before credential replacement is offered. A missing or unrecognized StatsD mapping requires the full setup review. The installer does not downgrade a newer config or mapping, and it leaves an unrecognized config unchanged.

The repair preview shows the complete relevant telemetry sections. Unchanged lines remain plain, additions start with +, and replaced values use - and +. Press Enter to apply the plan, enter e to edit the file in the same terminal, enter s for repair details, or enter q to stop. The installer resolves a selected xrpld.cfg symbolic link once and changes the regular target without changing the link. Automatic apply is not available when target sections or keys are ambiguous or when the target has hard links.

When a repair puts Alloy in front of an existing StatsD collector, the installer writes /var/lib/xrpl-monitoring-alloy/pending-relay before it changes xrpld.cfg. The root-owned mode 0600 file contains one line: the config path, Alloy listener, and existing relay address. It contains no credentials. On the next run, the installer uses the relay only when the config path and current StatsD address match the saved path and listener. It removes the file after the Alloy config is committed or when the original relay address is active again.

Changes The Installer May Request

StatsD must be enabled. If you are not already using StatsD, the installer asks you to add a block like this:

[insight]
server=statsd
address=127.0.0.1:9125
prefix=xrpld

If you already use StatsD, you do not need to change your existing prefix or lose your existing collector. The installer detects the current prefix and configures Alloy for it.

The only change the installer may ask for is the StatsD address, so xrpld sends packets to Alloy first. Alloy then acts as a middleman:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

The existing collector receives the original packets unchanged. The monitoring copy is handled separately by Alloy. If installation pauses after the address change, the protected pending-state record preserves the relay for the next run.

The debug log can use any path, as long as the file exists and Alloy can read it. Example:

[debug_logfile]
/var/log/xrpld/debug.log

The perf log must also be enabled:

[perf]
perf_log=/var/log/xrpld/perf.log
log_interval=2

The guided installer creates one protected original backup after the repair plan detects required xrpld.cfg changes and before it asks you to apply, edit, or stop. It keeps the backup next to the source file, confirms the path, and reuses that backup for all automatic or manual changes in the run. It does not create a config backup when the file needs no changes. The backup can contain validator secrets, so keep its original restrictive permissions. Approved automatic or manual changes are written before the restart question. Declining the restart leaves those changes in the file. If the restart fails, the installer offers to restore the original backup when it can safely replace the file. It checks the config again after restore approval and does not overwrite a concurrent change. Create your own backup when you use the manual installation path.

On xrpld package installs, the log directory is usually not readable by the Alloy service user. The installer detects this and asks before adding the alloy user to the log directory’s group so Alloy can read the logs. If a configured log directory is missing, the repair plan can create it with mode 0750 and the detected xrpld service owner. Its parent must be a real root-owned directory that is not writable by group or other users. Otherwise, create the log directory yourself and run the installer again. The installer changes the xrpld service state only when you approve the separate restart prompt.

Manual Install

The manual path follows the same order as the guided installer. Read each step before running its commands. Run them in Bash, in the same terminal, so values set in one step remain available in later steps. The examples use sudo. If you are already root, omit it from ordinary commands. Open files with your preferred editor instead of sudoedit, and follow the root-specific notes for service-user checks in steps 6 and 11.

1. Check The Host

Confirm the CPU architecture and operating system:

uname -m
cat /etc/os-release

For the supported production hosts listed above, uname -m prints x86_64. Also confirm that xrpld is running under systemd:

sudo systemctl status xrpld

On versions before 3.2.0, use rippled instead of xrpld in service commands.

2. Install Grafana Alloy

Grafana Alloy is installed from Grafana’s official package repository. These commands follow Grafana’s Linux installation guide. First check whether Alloy is already installed:

alloy --version

If this prints a version, skip the package commands and continue with step 3. Otherwise, use the section for your operating system.

Ubuntu Or Debian With APT

Install curl if it is not already available:

sudo apt-get update
sudo apt-get install -y curl

Download the Grafana signing key, add the repository, and install Alloy:

grafana_key="$(mktemp)"
curl -fsSL https://apt.grafana.com/gpg-full.key -o "$grafana_key"
sudo install -d -m 0755 /etc/apt/keyrings
sudo install -m 0644 "$grafana_key" /etc/apt/keyrings/grafana.asc
rm -f "$grafana_key"
grafana_repo='deb [signed-by=/etc/apt/keyrings/grafana.asc]'
grafana_repo="$grafana_repo https://apt.grafana.com stable main"
printf '%s\n' "$grafana_repo" \
  | sudo tee /etc/apt/sources.list.d/grafana.list
sudo apt-get update
sudo apt-get install -y alloy

RHEL With DNF Or YUM

Install curl if it is not already available:

sudo dnf install -y curl

Use yum in place of dnf if that is the package manager on your host. Download the Grafana signing key and add the repository:

grafana_key="$(mktemp)"
curl -fsSL https://rpm.grafana.com/gpg.key -o "$grafana_key"
sudo install -D -m 0644 "$grafana_key" \
  /etc/pki/rpm-gpg/RPM-GPG-KEY-grafana
sudo rpm --import "$grafana_key"
rm -f "$grafana_key"
sudo tee /etc/yum.repos.d/grafana.repo >/dev/null <<'EOF'
[grafana]
name=grafana
baseurl=https://rpm.grafana.com
repo_gpgcheck=1
enabled=1
gpgcheck=1
gpgkey=file:///etc/pki/rpm-gpg/RPM-GPG-KEY-grafana
sslverify=1
EOF
sudo dnf -y makecache --refresh
sudo dnf install -y alloy

Check the installed version:

alloy --version

3. Find And Back Up xrpld.cfg

The current package path is:

/etc/xrpld/xrpld.cfg

Older installations may use one of these paths:

/etc/opt/ripple/rippled.cfg
/opt/ripple/etc/rippled.cfg
/etc/rippled/rippled.cfg

If the file is elsewhere, systemctl cat xrpld or the command used to start xrpld may show a --conf path.

WarningBefore you start

Back up xrpld.cfg before changing it.

Replace the path below if your config is elsewhere:

sudo cp -a /etc/xrpld/xrpld.cfg /etc/xrpld/xrpld.cfg.bak.$(date +%s)
sudoedit /etc/xrpld/xrpld.cfg

Do not add a second copy of a section that already exists. Update the existing section instead.

4. Configure StatsD And Logs

Enable StatsD and both debug and perf logs in xrpld.cfg. Update existing sections instead of adding duplicates.

NoteLog paths are examples

You can keep your existing filenames and directories. Use paths that xrpld can write to, then give Alloy read access in step 6. In step 10, set log_debug and log_perf to those same paths.

Keep your existing non-empty StatsD prefix. Use it again in the mapping in step 8. If you already use a StatsD collector, read If Another StatsD Collector Already Exists before changing the address.

Example settings:

[insight]
server=statsd
address=127.0.0.1:9125
prefix=xrpld

[debug_logfile]
/var/log/xrpld/debug.log

[perf]
perf_log=/var/log/xrpld/perf.log
log_interval=2

If Another StatsD Collector Already Exists

Do not stop using it. Put Alloy in front of it so both systems receive the metrics.

For example, if xrpld currently sends to 127.0.0.1:8125:

  1. Keep 127.0.0.1:8125 as the relay address for the Alloy config.
  2. Choose a free local UDP port for Alloy, such as 127.0.0.1:9125 or 127.0.0.1:9126.
  3. Change only the [insight] address in xrpld.cfg to the new Alloy address.
  4. Keep the current StatsD prefix.

Check whether a UDP port is already in use:

sudo ss -lunp | grep ':9125 '

No output means the port is normally free. The final flow is:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

5. Apply Changes And Check The Inputs

Restart xrpld only if you changed xrpld.cfg in the previous step. Config changes do not take effect until the service restarts. Use your normal restart process. For a package install:

sudo systemctl restart xrpld

If you did not change xrpld.cfg, do not restart the service.

In either case, check that xrpld is running and that both log files exist:

sudo systemctl status xrpld
sudo ls -l /var/log/xrpld/debug.log /var/log/xrpld/perf.log

For a legacy service, use rippled in the service commands. Use your configured log paths if they are different.

6. Give Alloy Read Access To The Logs

First check whether the Alloy service user can read both files:

sudo -u alloy test -r /var/log/xrpld/debug.log && echo 'debug.log is readable'
sudo -u alloy test -r /var/log/xrpld/perf.log && echo 'perf.log is readable'

If you are working as root on a host without sudo, run the equivalent checks with runuser:

runuser -u alloy -- test -r /var/log/xrpld/debug.log && echo 'debug.log is readable'
runuser -u alloy -- test -r /var/log/xrpld/perf.log && echo 'perf.log is readable'

If both messages appear, continue to the next step. If not, check the group that owns the log directory:

sudo stat -c '%U %G %a %n' /var/log/xrpld

If the group is not root, add the alloy user to it. The group is commonly named xrpld:

sudo usermod -aG xrpld alloy

If the stat command showed another non-root group, use that group name instead.

If the directory uses the root group, never add the alloy user to that group. Instead, give the Alloy group access only to the log directory and the two configured log files:

sudo chgrp alloy /var/log/xrpld
sudo chgrp alloy /var/log/xrpld/debug.log /var/log/xrpld/perf.log
sudo chmod g+rx /var/log/xrpld
sudo chmod g+r /var/log/xrpld/debug.log /var/log/xrpld/perf.log

These commands keep each file’s owner unchanged. If root owns a file, its ownership becomes root:alloy. Use your configured directory and file paths if they are different.

Run the two read checks again and do not continue until both messages appear. Do not make validator logs readable by every user. Check access again after log rotation in case the files are created with their old group.

7. Download The Shared XRPL Config

The shared config contains the StatsD, metrics, log processing, redaction, and push settings used by all validators. It contains no validator credentials. Download it without installing it first:

module_tmp="$(mktemp)"
curl -fsSL \
  https://push.monitoring.xrplf.org/alloy/config \
  -o "$module_tmp"
printf 'Downloaded to: %s\n' "$module_tmp"

Open the downloaded file in a text editor if you want to review every setting. Then check that it contains the expected module:

grep -F 'Managed by xrpl-monitoring Alloy installer' "$module_tmp"
grep -F 'declare "xrplf"' "$module_tmp"

Both commands must print a matching line. Install the reviewed file:

sudo install -d -m 0755 /etc/alloy
sudo install -m 0644 "$module_tmp" /etc/alloy/xrplf.alloy
rm -f "$module_tmp"

8. Create The StatsD Mapping

Create the mapping file:

sudoedit /etc/alloy/statsd-mapping.yml

For the standard prefix=xrpld, paste:

defaults:
  match_type: regex

mappings:
  - match: '^xrpld[.](.+)$'
    name: 'xrpld_${1}'

  - match: '.*'
    action: drop
    name: 'dropped'

The first match must use the same prefix as [insight]. For example, prefix=rippled needs ^rippled[.](.+)$. A literal dot in a custom prefix must be written as [.], and a literal hyphen can be written as [-]. The last rule drops unrelated StatsD packets from the monitoring path.

Set the file permissions:

sudo chmod 0644 /etc/alloy/statsd-mapping.yml

9. Create The Protected Password File

Find the Alloy service account and create the password file without a final newline:

alloy_user="$(systemctl show alloy.service -p User --value)"
alloy_group="$(systemctl show alloy.service -p Group --value)"
[ -n "$alloy_user" ] || alloy_user=root
[ -n "$alloy_group" ] || alloy_group="$(id -gn "$alloy_user")"

(
  set -e
  umask 077
  password_tmp="$(mktemp)"
  trap 'rm -f -- "$password_tmp"' EXIT
  printf '%s' 'Monitoring push password: ' >&2
  IFS= read -r -s xrpl_push_password
  printf '\n' >&2
  printf '%s' "$xrpl_push_password" >"$password_tmp"
  unset xrpl_push_password

  sudo install -d -o root -g "$alloy_group" -m 0750 /etc/alloy
  sudo install -o root -g "$alloy_group" -m 0640 \
    "$password_tmp" /etc/alloy/xrpl-push
)

The file must contain only the password and must not have a final newline. Alloy reads it as a secret, so the password stays redacted in the local Alloy API, UI, and support bundle.

10. Create The Host Config

The package normally creates a default /etc/alloy/config.alloy. Review it before replacing it:

sudo less /etc/alloy/config.alloy

Press q to close less.

WarningExisting Alloy setup

If the file contains a setup you already use, do not replace it. Plan how to merge the XRPL settings with the person who manages that setup.

If the file is only the package default, back it up and open it for editing:

sudo cp -a /etc/alloy/config.alloy /etc/alloy/config.alloy.bak.$(date +%s)
sudoedit /etc/alloy/config.alloy

Paste the following config and replace every value inside angle brackets. If you do not use a public validator master key, set validator_master_key = "". Never enter a validator token, seed, or private key.

Host metrics are disabled in this example. See Optional Host Metrics to enable them.

// XRPL validator monitoring config.

import.file "xrpl_monitoring" {
  filename = "/etc/alloy/xrplf.alloy"
}

local.file "xrpl_monitoring_password" {
  filename  = "/etc/alloy/xrpl-push"
  is_secret = true
}

xrpl_monitoring.xrplf "default" {
  node                 = "<node-label>"
  validator_master_key = "<public-validator-master-key>"
  host_metrics_enabled = false

  push_host = "push.monitoring.xrplf.org"

  username = "<basic-auth-username>"
  password = local.file.xrpl_monitoring_password.content

  log_debug = "/var/log/xrpld/debug.log"
  log_perf  = "/var/log/xrpld/perf.log"

  statsd_listen     = "127.0.0.1:9125"
  statsd_relay_addr = ""

  // Keep "^$" when no extra redaction is needed.
  host   = "^$"
  pubkey = "^$"
}

logging {
  format = "logfmt"
  level  = "info"
}

Use these values:

  • node: a short label for this host. The full hostname is a good default.
  • validator_master_key: the optional public 52-character validator master key that starts with nH. Use an empty string ("") to opt out. Never use a validator token, signing key, private key, or seed.
  • host_metrics_enabled: a bare true or false value. Keep false unless you choose to send basic host metrics.
  • username: Basic Auth username from the XRPL Foundation.
  • password: the secret content exported by local.file, do not put a literal password in config.alloy.
  • log_debug and log_perf: exact paths from xrpld.cfg.
  • statsd_listen: exact [insight] address from xrpld.cfg.
  • statsd_relay_addr: the old collector address, or an empty string if there is no other collector.

Alloy strings use double quotes. If a value itself contains " or \, put a backslash before that character.

The config does not contain the monitoring password, but it still contains private local monitoring details. Give the Alloy service group read access, but do not make the file public:

alloy_group="$(systemctl show alloy.service -p Group --value)"
sudo chown "root:${alloy_group:-alloy}" /etc/alloy/config.alloy
sudo chmod 0640 /etc/alloy/config.alloy

11. Validate And Start Alloy

Check the password file contract, then validate the complete config:

sudo test -s /etc/alloy/xrpl-push
sudo test ! -L /etc/alloy/xrpl-push
sudo -u "$alloy_user" test -r /etc/alloy/xrpl-push
sudo stat -c '%U:%G %a %n' /etc/alloy/xrpl-push
sudo python3 -c '
data = open("/etc/alloy/xrpl-push", "rb").read()
raise SystemExit(1 if data.endswith(b"\n") else 0)
'
sudo alloy validate /etc/alloy/config.alloy

If you are working as root on a host without sudo, replace the service-user readability check with:

runuser -u "$alloy_user" -- test -r /etc/alloy/xrpl-push

The stat output must show root, the Alloy service group, and mode 640. The Python command must exit successfully without output.

Do not start Alloy if validation reports an error. Fix the named file and run the check again.

If Alloy is not running, start it:

sudo systemctl start alloy

If it was already running with the package’s default config, restart it:

sudo systemctl restart alloy

Enable Alloy so it starts after a reboot:

sudo systemctl enable alloy.service

Starting or restarting Alloy begins sending the configured metrics and logs to push.monitoring.xrplf.org.

12. Verify The Manual Install

Check the service:

sudo systemctl status alloy

Check its recent logs:

sudo journalctl -u alloy -n 100 --no-pager

The status should be active and the logs should not show repeated read, config, authentication, or push errors. After a few minutes, continue to Grafana Setup & Access and confirm that the node appears in the dashboards.

Configuration Reference

Both setup paths use the same four files: the guided installer writes them for you, while the manual path has you create them yourself.

/etc/alloy/config.alloy
/etc/alloy/xrpl-push
/etc/alloy/xrplf.alloy
/etc/alloy/statsd-mapping.yml

Most operators do not need to edit the files after setup. It is useful to know what they contain.

/etc/alloy/xrpl-push contains only the push password, has no final newline, and is written with owner root, the Alloy service group, and mode 0640.

/etc/alloy/config.alloy loads the password as an Alloy secret. It does not contain the literal password and is written with mode 0640.

/etc/alloy/xrplf.alloy contains the shared XRPL telemetry module and is written with mode 0644.

/etc/alloy/statsd-mapping.yml contains no secrets and is written with mode 0644.

/var/lib/xrpl-monitoring-alloy/pending-relay is a temporary guided installer record, not an Alloy config file. Its one line contains the config path, Alloy listener, and existing relay address. It exists only while an approved relay change is waiting for the Alloy config to be committed. The containing directory is root-owned mode 0700, and the file is root-owned mode 0600.

The guided installer backs up an existing file before replacing it:

<path>.bak.<unix-seconds>

The manual path shows the backup command before you replace the package config.

Values You Should Recognize

This table explains the general settings. Keep reading for details on host metrics, validator correlation, redaction, StatsD, and logs.

Setting What it does
node Sets the node label shown in Grafana.
push_host Sets the monitoring host, without https:// or a path.
username Sets the Basic Auth username from the XRPL Foundation.
password Loads the secret from /etc/alloy/xrpl-push.

All generated connections to the push host use HTTPS.

Optional Host Metrics

Host metrics are disabled by default. To enable them, set this value in /etc/alloy/config.alloy, validate the config, and restart Alloy:

host_metrics_enabled = true

Alloy then collects CPU, memory, load, filesystem, disk, network, system time, kernel, and virtual-memory metrics every 15 seconds. The metrics use job="node_exporter", service_name="node_exporter", and the configured node label for both node and instance. They use the existing Mimir connection and monitoring tenant.

The host pipeline does not add validator_master_key. It drops disk identity metrics and real hostname labels. View enabled host metrics in the XRPL Validator Resources dashboard. This option does not add host alerts. Set the value to false, validate the config, and restart Alloy to stop new host samples. Historical samples remain until backend retention removes them.

Optional Validator Correlation

Set validator_master_key to the validator’s public 52-character master key that starts with nH to correlate the collector with public XRPL network statistics. This is not an account address, signing key, private key, seed, or validator token. Leave the value exactly empty to opt out:

validator_master_key = ""

The public master key is attached only to the Prometheus up metric. It is not attached to other metrics or any Loki log stream, and it does not replace the Basic Auth tenant as the trusted identity. After changing the value, validate the config and restart Alloy.

Optional Redaction

Host or public-key redaction is optional. The guided installer does not ask for it, and the manual config leaves it disabled.

By default, the generated config contains:

host   = "^$"
pubkey = "^$"

^$ is the disabled value. Keep it when no extra redaction is needed.

Alloy always redacts IPv4 and IPv6 addresses from debug.log. To also redact a host, domain, or public key, edit /etc/alloy/config.alloy after install and replace one or both values with a regex that matches only the value you want to hide.

  • host redacts matching host or domain values from debug.log and perf.log.
  • pubkey redacts matching public-key values from debug.log.

Example:

host   = "validator[.]example[.]com"
pubkey = "n9KExamplePublicKey"

Then restart Alloy:

sudo systemctl restart alloy

Do not use broad patterns such as .*, because every match is replaced in the logs. Keep the config file private because it contains local monitoring details. The password is stored separately in /etc/alloy/xrpl-push.

StatsD

xrpld sends StatsD packets to Alloy. Set statsd_listen to the same address as [insight] address in xrpld.cfg. Alloy converts the packets into metrics for the Grafana dashboards.

The mapping file keeps only the configured StatsD prefix and drops unrelated StatsD packets from the monitoring path.

If another StatsD collector already exists, Alloy sits in front of it:

xrpld -> Alloy -> existing StatsD collector
              |
              +-> XRPL monitoring

In that setup, the guided installer configures statsd_relay_addr automatically. In the manual path, you enter the old collector address yourself. The existing collector receives the original packets unchanged.

Logs

Alloy reads the files selected by log_debug and log_perf. Set these to the exact paths in xrpld.cfg. The filenames and directories can be different from the examples.

It parses timestamps, adds dashboard labels, applies the built-in and optional redaction described above, and sends the logs to the monitoring platform.

Useful service commands:

sudo systemctl status alloy
sudo journalctl -u alloy -n 100 --no-pager
sudo systemctl restart alloy
sudo systemctl stop alloy

Grafana Setup & Access

The XRPL Foundation provides Grafana account access. Open:

https://monitoring.xrplf.org

After Alloy starts, wait a few minutes, then open:

  • XRPL Validator Health
  • XRPL StatsD Metrics
  • XRPL Logs & Triage

If you opt in to host metrics, open XRPL Validator Resources to check them.

Use the dashboard filters:

  • validator: the monitoring tenant.
  • node: the node label entered during install.
  • For logs: file, level, and module.

If data does not appear:

  • Check Alloy:

    sudo systemctl status alloy

  • Check Alloy logs:

    sudo journalctl -u alloy -n 100 --no-pager

  • Confirm xrpld is sending StatsD to the same address Alloy listens on.

  • Confirm debug.log and perf.log paths exist and are readable.

  • Confirm the push host and credentials with the XRPL Foundation.

Uninstall

Guided Uninstall

If you used the guided installer, run:

curl -fsSL \
  https://push.monitoring.xrplf.org/alloy/install \
  | bash -s -- --uninstall

The uninstall flow asks before it:

  • Stops Alloy.
  • Disables Alloy at boot.
  • Removes managed /etc/alloy files.
  • Removes the Grafana package repository and signing key.
  • Removes the alloy package.

/etc/alloy/xrpl-push holds the monitoring push password. The installer asks before removing it without a backup. It also removes the managed config without a backup and offers to remove leftover config.alloy copies because legacy backups can contain a literal password.

It does not touch xrpld.cfg. If the install put Alloy in front of an existing StatsD collector, the uninstall prints the original collector address so you can restore the [insight] address yourself and restart xrpld using your normal process. The uninstall removes a valid pending relay-state record after it reads that address and removes a managed Alloy file or package.

Manual Uninstall

First stop Alloy and disable it at boot:

sudo systemctl stop alloy
sudo systemctl disable alloy

If you put Alloy in front of an older StatsD collector, restore the old [insight] address in xrpld.cfg now and restart xrpld using your normal process.

Remove the four config files. Check any backup before removing it because legacy config.alloy backups may contain the monitoring password:

sudo rm -i /etc/alloy/config.alloy
sudo rm -i /etc/alloy/xrpl-push
sudo rm -i /etc/alloy/xrplf.alloy
sudo rm -i /etc/alloy/statsd-mapping.yml
sudo find /etc/alloy -maxdepth 1 \
  \( -name 'config.alloy.bak.*' -o -name 'config.alloy.rpmsave' \) \
  -exec rm -i {} \;

Remove the package with the command for your operating system:

sudo apt-get remove alloy

Or:

sudo dnf remove alloy

The Grafana repository can stay in place for package updates or other Grafana software. If you want to remove it too, follow the optional repository-removal step in Grafana’s Linux uninstall guide.

Disable Without Removing Alloy

To stop monitoring but keep the package and config:

sudo systemctl stop alloy
sudo systemctl disable alloy

If you changed xrpld.cfg to send StatsD to Alloy and want to go back to a previous collector, restore the previous [insight] address yourself and restart xrpld using your normal process.

Back to top