Orbit Metrics

Orbit Metrics is a Prometheus exporter for Cosmos SDK chains. It reads chain height, wallet balances, validator stake and on-chain parameters from each chain's REST API and serves them as metrics.

Source on GitHub · Summary on chaintools.tech · MIT licence

Requirements

Python 3 (3.8 or newer recommended)
A REST (LCD) endpoint for each chain — your own node or a public one such as ours

Install

bash

git clone https://github.com/ChainTools-Tech/orbit_metrics.git && cd orbit_metrics
python3 -m venv .venv && . .venv/bin/activate
pip install .

Configuration

yaml

nodes:
  - name: BitSong
    api_url: https://api.bitsong.chaintools.tech
    main_denom: ubtsg
    wallets:
      - address: bitsong1...
        type: validator
    validators:
      - validator_id: bitsongvaloper1...

Key	Meaning
`name`	Label used for the `chain` label of every metric
`api_url`	REST endpoint of the chain
`main_denom`	Denom whose balance is reported for each wallet
`wallets[]`	`address`, and an optional `type` used as a label (default `unknown`)
`validators[]`	`validator_id`: the validator operator address

Usage

bash

orbit_metrics --config config.yml --log-file orbit_metrics.log --log-level INFO

Option	Default	Meaning
`--config`	— (required)	Configuration file
`--log-file`	`orbit_metrics.log`	Log file, rewritten on start
`--log-level`	`INFO`	`DEBUG`, `INFO`, `WARNING`, `ERROR` or `CRITICAL`

Metrics are served on port 8000 and refreshed every 60 seconds; neither is configurable. Delegator Tracker also uses port 8000, so the two can't run on the same host; Cert Expiry Checker can be moved to another port. Add the exporter to Prometheus:

yaml

scrape_configs:
  - job_name: orbit_metrics
    static_configs:
      - targets: ['<HOST>:8000']

Metrics

All metrics are gauges. Every metric has a chain label (the configured name).

Metric	Extra labels	Value
`orbit_metrics_chain_height`	`chain_id`, `host` (node moniker)	Latest block height
`orbit_metrics_wallet_balance`	`chain_id`, `wallet`, `type`	Balance in `main_denom` (base units)
`orbit_metrics_validator_stake`	`chain_id`, `validator`	Validator tokens (base units)
`orbit_metrics_community_tax`		Distribution: community tax
`orbit_metrics_base_proposer_reward`		Distribution: base proposer reward
`orbit_metrics_bonus_proposer_reward`		Distribution: bonus proposer reward
`orbit_metrics_withdraw_addr_enabled`		Distribution: 1 if enabled, else 0
`orbit_metrics_inflation_rate_change`	`mint_denom`	Mint: inflation rate change
`orbit_metrics_inflation_max`	`mint_denom`	Mint: maximum inflation
`orbit_metrics_inflation_min`	`mint_denom`	Mint: minimum inflation
`orbit_metrics_goal_bonded`	`mint_denom`	Mint: goal bonded ratio
`orbit_metrics_blocks_per_year`	`mint_denom`	Mint: blocks per year
`orbit_metrics_signed_blocks_window`		Slashing: signed blocks window
`orbit_metrics_min_signed_per_window`		Slashing: minimum signed per window
`orbit_metrics_downtime_jail_duration`		Slashing: downtime jail duration (seconds)
`orbit_metrics_slash_fraction_double_sign`		Slashing: double-sign slash fraction
`orbit_metrics_slash_fraction_downtime`		Slashing: downtime slash fraction
`orbit_metrics_unbonding_time`	`bond_denom`	Staking: unbonding time (seconds)
`orbit_metrics_max_validators`	`bond_denom`	Staking: maximum validators
`orbit_metrics_max_entries`	`bond_denom`	Staking: maximum entries
`orbit_metrics_historical_entries`	`bond_denom`	Staking: historical entries
`orbit_metrics_bonded_tokens`		Staking pool: bonded tokens
`orbit_metrics_not_bonded_tokens`		Staking pool: not bonded tokens

The values come from the chain's cosmos/{bank,staking,distribution,mint,slashing} REST endpoints. Chains without the mint module (or with a custom one) simply don't report the mint metrics.

INFO

The metric names and labels above are taken from the code; the repository README still lists older names (orbit_*).

Orbit Metrics ​

Requirements ​

Install ​

Configuration ​

Usage ​