All tools
Orbit Metrics
Prometheus exporter for Cosmos SDK chain height, wallet balances, validator stake and chain parameters
View on GitHub
Best forPrometheus-based observability
Overview
Orbit Metrics is a monitoring tool for Cosmos SDK-based blockchains. It collects chain height, wallet balances, validator stake and a set of on-chain parameters from the REST API of each configured chain and exposes them as Prometheus metrics.
With the metrics in Prometheus, chain data can be visualised in Grafana and used for alerting alongside node and infrastructure monitoring.
Key Features
- Chain height and ID — Fetches the current height and chain ID from multiple nodes.
- Wallet balances — Monitors balances of specific addresses, labelled by wallet type.
- Validator stake — Collects the stake amount of configured validators.
- Chain parameters — Exposes distribution, mint, slashing and staking parameters, plus staking pool totals.
- Prometheus compatible — Everything is exported as Prometheus gauges.
Installation
git clone https://github.com/ChainTools-Tech/orbit_metrics.git
cd orbit_metrics
python -m venv venv
source venv/bin/activate
pip install .Configuration
Create config.yml with the chains, wallets and validators to monitor:
nodes:
- name: BitSong
api_url: http://api.bitsong.example.com
main_denom: ubtsg
wallets:
- address: bitsong1...
type: validator
validators:
- validator_id: bitsongvaloper1...| Field | Description |
|---|---|
name | Friendly name of the chain |
api_url | Base URL of the REST API endpoint |
main_denom | Main denomination of the chain |
wallets | Addresses to monitor, each with a type (e.g. validator, savings) |
validators | Validator IDs to monitor |
Usage
python -m orbit_metrics --config config.yml --log-file orbit_metrics.log --log-level DEBUG| Option | Description |
|---|---|
--config | Path to the configuration file |
--log-file | Path to the log file |
--log-level | DEBUG, INFO, WARNING, ERROR or CRITICAL |
Exported Metrics
All metrics are gauges.
| Metric | Labels | Description |
|---|---|---|
orbit_chain_height | chain, chain_id, moniker | Current height of the blockchain |
orbit_wallet_balance | chain, chain_id, wallet, type | Balance of the specified wallet address |
orbit_validator_stake | chain, chain_id, validator, moniker | Stake amount of the specified validator |
orbit_community_tax | chain, moniker | Community tax rate |
orbit_base_proposer_reward | chain, moniker | Base proposer reward rate |
orbit_bonus_proposer_reward | chain, moniker | Bonus proposer reward rate |
orbit_withdraw_addr_enabled | chain, moniker | Whether withdrawal addresses are enabled |
orbit_mint_inflation_rate_change | chain, mint_denom, moniker | Inflation rate change for minting |
orbit_slashing_signed_blocks_window | chain, moniker | Signed blocks window for slashing |
orbit_staking_unbonding_time | chain, bond_denom, moniker | Unbonding time in seconds |
orbit_staking_pool_bonded_tokens | chain, moniker | Bonded tokens in the staking pool |
orbit_staking_pool_not_bonded_tokens | chain, moniker | Not-bonded tokens in the staking pool |
Related Resources
- Full documentation — Requirements, installation and usage on docs.chaintools.tech
- Prometheus documentation — Scraping and alerting on the metrics
- Grafana documentation — Building dashboards on Prometheus data
- Cosmos SDK documentation — Staking, slashing, mint and distribution parameters
Need something custom?
We build tooling and automation for node operators and chain teams, and can help you deploy or adapt this tool to your setup.