Skip to main content

Cosmos Node Exporter

Cosmos Node Exporter is a Prometheus scraping tool designed to monitor your node. It enables you to set up alerting for various critical conditions, such as:

  • Notification for new releases: Receive alerts when your application version doesn't match the latest release on GitHub, keeping you informed about important updates.
  • Voting Power Monitoring: Get alerted if the voting power of your validator node drops to zero, helping you quickly address any issues affecting your node's participation in the network.
  • Node Synchronization: Stay informed about the progress of your node's synchronization, ensuring that it doesn't fall behind and remains up-to-date with the network.
  • Chain Upgrade Readiness: Receive notifications when chain upgrades are available, but your node lacks the necessary binary files, ensuring that your node is always prepared for network upgrades.

Validator Machine

Execute the following operations on your validator machine

Download & Installation

To get started, begin by downloading the most recent release. Once the download is complete, proceed to unzip the file, and you'll be all set to proceed.

mkdir cosmos-node-exporter
cd cosmos-node-exporter
tar xvfz cosmos-node-exporter_X.X.X_linux_amd64.tar.gz
sudo rm -f cosmos-node-exporter_X.X.X_linux_amd64.tar.gz

Add a symbolic link to the /usr/local/bin/ directory for system-wide access to Cosmos Node Exporter:

sudo ln -s /home/${USER}/cosmos-node-exporter/cosmos-node-exporter /usr/local/bin/

Create a Config file

Inside your cosmos-node-exporter directory create the config file:

nano config.toml

Paste the following code in it making sure to edit the fields between < and > characters


# Logging configuration.
# Verbosity level. Set to `debug` or even `trace` to make it more verbose. Defaults to `info`.
level = "debug"
# Whether to print logs in JSON format. Useful if you are using centralised logs solutions like ELK.
# Defaults to false.
json = false

# Per-node configuration, there can be multiple nodes.
# Node name. Will be displayed in labels. Required.
name = "<your_node_name>"

# Tendermint configuration. Has the following fields:
# 1. enabled. If set to false, the metrics related to Tendermint node would be disabled. Defaults to true.
# 2. address. Tendermint RPC address. Defaults to "http://localhost:26657".
# 3. query-upgrades. If set to false, upgrades metrics won't be queried. Useful for chains that use Tendermint
# but not cosmos-sdk, such as Nomic. Defaults to true.
tendermint = { enabled = true, address = "http://localhost:26657", query-upgrades = true }

# Cosmovisor configuration. Has the following fields:
# 1. enabled. # If set to false, the metrics related to Cosmovisor would be disabled. Defaults to true.
# 2. chain-folder. Path to folder storing fullnode data and configs (like ~/.gaia for cosmoshub).
# 3. chain-binary-name. Binary name (like gaiad for cosmoshub)
# 4. cosmovisor-path. Cosmovisor path (usually located at ~/go/bin/cosmovisor)
cosmovisor = { enabled = true, chain-folder = "/home/<your_user>/.sentinelhub", chain-binary-name = "sentinelhub", cosmovisor-path = "/home/<your_user>/go/bin/cosmovisor" }

# Git configuration. Has the following fields:
# 1. repository. Repository path. Omitting it will result in disabling Git metrics.
# Can be either a link to Github repo (like below), or a Gitopia repo (see below for example).
# 2. token. Github token. Useful if you want to make requests often, as Github rate-limits requests
# if no token is specified. Only used for Github.
git = { repository = "", token = "<your_github_token>" }

Add a system unit file

Create the .service file with a text editor

sudo nano /etc/systemd/system/cosmos-node-exporter.service

Paste the below text


Description=Cosmos Node Exporter

User=<your_user> #modify this field with your user
ExecStart=cosmos-node-exporter --config /home/<your-user>/cosmos-node-exporter/config.toml


Reload the systemd Daemon

sudo systemctl daemon-reload

Enable autostart of Cosmos Node Exporter service

sudo systemctl enable cosmos-node-exporter.service

Start Cosmos Node Exporter service

sudo systemctl start cosmos-node-exporter.service

Use this command to check logs in real time

sudo journalctl -u cosmos-node-exporter.service -f --output cat

Once the Cosmos Node Exporter is installed and running, you can verify that metrics are being exported by cURLing the /metrics endpoint:

curl http://localhost:9500/metrics

Success! Cosmos Node Exporter is now exposing metrics that Prometheus can scrape, including a wide variety of system metrics further down in the output.

Open Firewall Port


After successfully installing and launching Cosmos Node Exporter, the next step is to open port 9500 on your Validator's firewall. This port should be accessible exclusively from your monitoring machine. This action is essential to enable Prometheus to collect data from Cosmos Node Exporter.

sudo ufw allow from monitor_ip to validator_ip port 9500

Monitoring Machine

On your monitoring machine, go to your prometheus directory and open your prometheus.yml file

sudo nano prometheus.yml

Add the cosmos node exporter job into it, under scrape_configs block

 # Cosmos Node Exporter
- job_name: "cosmos-node-exporter"

- targets: ["<your_validator_ip>:9500"]