Adding Pool Stats to Grafana Dashboard

So, you’ve set up your stake pool and followed the instructions to install an awesome Grafana dashboard to monitor your pool’s performance and statistics? That’s awesome! What would be even more awesome is if you could also see your current delegation statistics from ADAPools (adapools.org) so you’ve got a one-stop-shop for all your pool information at a glance!

Screenshot of Crypto2099 Grafana Dashboard
Sick dashboard, bro!

Well, you’re in luck. In this blog post I’ll walk you through the steps to fetch JSON data from ADAPools, format and save it to your server, and then collect those statistics using node_exporter into Prometheus and on to your Grafana dashboard!

To do this, we’re going to query the ADAPools JSON Pool Summary file which can be found from the “Share” tab of a pool on ADAPools [as shown in the screenshot below]. The format of this link as of the time of this writing is: https://js.adapools.org/pools/000022b3f0b748a43239c5024c58f852c05593cd0a77a798f0bb3a14/summary.json. The link shown here is for our BUFFY pool but you can simply replace BUFFY’s pool ID (000022b3f0b748a43239c5024c58f852c05593cd0a77a798f0bb3a14) with your Pool ID and you’re off to the races.

ADAPools JSON Summary Location
Just look up your pool at ADAPools.org to find your unique link!

Anyway, onwards and upwards. So we can fetch the JSON data for our pool but we need to get this data into a format that can be consumed by Prometheus and we’re going to use node_exporter’s built-in textfile collector to do it.

What’s the catch?

Okay, so the catch with this method is that node_exporter can only import numeric values and will throw a fit and refuse to import anything if it encounters a bad value. So, we need to download the file from ADAPools, remove the “offending” JSON fields, and export to a text file that node_exporter can then read and send to Prometheus. Easy, right? Turns out, it’s pretty straightforward.

Note: you do need to have jq installed on your machine for this to work, so make sure you install via the relevant package manager for your flavor of Linux.

You can find more details about how the node_exporter textfile.collector works from the Prometheus node_exporter GitHub repo.

TL;DR: We need to create a special directory that node_exporter will check for formatted (*.prom) text files that it will slurp into the exported metrics.

Disclaimer: use all code examples in this post at your own risk. Make sure you substitute any values enclosed in angular brackets <variable> with info from your setup.

Set Up the Stat Collection Folder and Script

cd ~/cardano-node # Your cardano-node installation directory, this may be different on your system
mkdir -p pool.stats # You can rename this to whatever you like
cd pool.stats
echo "curl https://js.adapools.org/pools/<your-pool-id>/summary.json 2>/dev/null \
| jq '.data | del(.hist_bpe, .handles, .hist_roa, .db_ticker, .db_name, .db_url, .ticker_orig, .pool_id)' \
| tr -d \\\"{},: \
| awk NF \
| sed -e 's/^[ \t]*/adapools_/' > adapools.prom" > getstats.sh
chmod +x getstats.sh
./getstats.sh

Edit: Previously the script above was out of order so the adapools.prom file was being written without properly prefixing adapools_ in front of the stats. The version shown above should be correct.

Update: some users have experienced issues using the echo command above to create the getstats.sh file. If you encounter runtime issues, use your favorite text editor and make sure that the getstats.sh file looks like the example below:

curl https://js.adapools.org/pools/<your-pool-id>/summary.json 2>/dev/null \
| jq '.data | del(.hist_bpe, .handles, .hist_roa, .db_ticker, .db_name, .db_url, .ticker_orig, .pool_id)' \
| tr -d \"{},: \
| awk NF \
| sed -e 's/^[ \t]*/adapools_/' > adapools.prom

After properly executing the code above, you should now see an adapools.prom file in your pool.stats folder with content similar to the following:

$ cat adapools.prom
adapools_id 38
adapools_db_verified 1
adapools_total_stake 21943036915617
adapools_rewards_epoch 0
adapools_tax_ratio 0.0258
adapools_tax_fix 340000000
adapools_roa 0
adapools_blocks_epoch 0
adapools_blocks_lifetime 0
adapools_stamp_amba 0
adapools_stamp_trophy 0
adapools_stamp_supporter 0
adapools_stamp_strike 0
adapools_pledge 1100000000000
adapools_itn_count 1
adapools_itn_status 1
adapools_metric 34.693387267057
adapools_delegators 49
adapools_pledged 1100100000000
adapools_tax_real 3.4123228305753
adapools_active_stake 21020182486075
adapools_saturated 0.10589801555653
adapools_rank 287

Later, the statistics above will be imported into our Prometheus instance for use in your Grafana dashboard.

Getting these stats into node_exporter

Okay, so we’ve got a stats file, but now we need to tell node_exporter where to look for these *.prom files to import. There are many different ways of calling node_exporter but I personally set up a systemd service so that node_exporter will always automatically run on a system restart. We tell node_exporter to consume *.prom files with two command line argument flags:

  • –collector.textfile
  • –collector.textfile.directory=”</path/to/your/stats/directory>”

In my case, this looks like the following:

ExecStart=/usr/local/bin/node_exporter --collector.textfile.directory="/home/<user>/cardano-node/node.stats" --collector.textfile

If you run by manually triggering the node_exporter from the command line it might look like the following:

./node_exporter --collector.textfile.directory="/home/<user>/cardano-node/node.stats" --collector.textfile

Note: If you run node_exporter as a service make sure that you reload the daemons and restart the service in order for your changes to take effect.

sudo systemctl daemon-reload
sudo systemctl restart node_exporter

After you have restarted node_exporter with the text file collector flags, you should be able to check the node exporter metrics by visiting http://localhost:9100/metrics on your local machine and see the newly created metrics.

Using the stats in Grafana

Because we prefixed each line of our *.prom file with adapools_ we will be able to find the ADAPools metrics under that name when adding a new panel to our Grafana dashboard.

From there, the sky’s the limit and I can’t wait to see what sort of awesome tools the community comes up with to use these statistics to make even more beautiful operator dashboards!