Configure StatsD

rippled can export health and behavioral information about itself in StatsD format. Those metrics can be consumed and visualized through rippledmon or any other collector that accepts StatsD formatted metrics.

To enable StatsD on your xrpld server, perform the following steps:

1. Set up a rippledmon instance on another machine to receive and aggregate stats.

   $ git clone https://github.com/ripple/rippledmon.git
   $ cd rippledmon
   $ docker-compose up

   Make sure Docker and Docker Compose are installed on your machine when performing the steps above. For more information about configuring rippledmon, see the rippledmon repository.

2. Add the [insight] stanza to your xrpld's config file.

   [insight]
   server=statsd
   address=192.0.2.0:8125
   prefix=my_rippled

   • For the address, use the IP address and port where rippledmon is listening. By default, this port is 8125.
   • For the prefix, choose a name that identifies the xrpld server you are configuring. The prefix must not include whitespace, colons ":", or the vertical bar "|". The prefix appears on all of the StatsD metrics exported from this server.

   The recommended installation uses the config file /etc/xrpld/xrpld.cfg by default. Other places you can put a config file include $HOME/.config/xrpld/xrpld.cfg (where $HOME is the home directory of the user running rippled), $HOME/.local/xrpld/xrpld.cfg, or the current working directory from where you start rippled.

   The config file was renamed from rippled.cfg to xrpld.cfg. During the transition, if xrpld.cfg is not present the server still reads rippled.cfg from the same locations, so existing config files keep working without being renamed.

3. Restart the xrpld service.

   $ sudo systemctl restart xrpld

4. Check that the metrics are being exported:

   $ tcpdump -i en0 | grep UDP

   Replace en0 with the appropriate network interface for your machine. For a complete list of the interfaces on your machine use $ tcpdump -D.

   Sample Output:

   00:41:53.066333 IP 192.0.2.2.63409 > 192.0.2.0.8125: UDP, length 196

   You should periodically see messages indicating outbound traffic to the configured address and port of your rippledmon instance.

After you enable StatsD, the core server exports metrics about its own health and behavior. Each metric arrives as <prefix>.<group>.<metric>, where prefix is the value you set in the [insight] stanza and group is the server subsystem that reports it. For example, with prefix=my_xrpld, the validated ledger age arrives as my_xrpld.LedgerMaster.Validated_Ledger_Age.

All of the metrics in this section are reported as StatsD gauges. Cumulative values are not reset between reports, so calculate rates in your collector. For the complete list of exported metrics, see the rippledmon repository.

These metrics report how long the server has spent in each operational state and how many times it has entered each one. The core server tracks five accounting states: Disconnected, Connected, Syncing, Tracking, and Full. The xrpld Server States reference lists seven states, but validating and proposing aren't tracked separately here; time the server spends in those states is counted under Full_duration.

tcpdump -A -i lo udp port 8125

If your collector runs on a different machine, use that machine's network interface instead. Replace lo with the interface your StatsD traffic crosses, and 8125 with the port your collector listens on. When the collector runs on the same host as the server, that traffic stays on the loopback interface, which is lo on Linux and lo0 on macOS. On Linux you can also pass any to capture on every interface. Each metric appears in the payload as <prefix>.<group>.<metric>:<value>|<type>.

• Concepts:
  • XRP Ledger Overview
  • The xrpld Server
• Tutorials:
  • Install xrpld
  • Capacity Planning
• References:
  • server_info method
  • print method