Orbit Metrics

Monitor Cosmos blockchains with Prometheus-compatible metrics

ChainTools

Overview

Orbit Metrics is a monitoring tool for Cosmos-based blockchains that collects and exports key metrics related to chain height, wallet balances, validator stakes, and various parameters. It is designed to work seamlessly with Prometheus, allowing for easy visualization and analysis of blockchain data.

Monitoring blockchain networks is essential for validators, operators, and developers. Orbit Metrics simplifies this process by collecting relevant metrics from Cosmos-based blockchains and exposing them in a format that can be easily integrated with monitoring systems like Prometheus and Grafana.

The tool supports monitoring multiple chains simultaneously and can track a wide range of metrics, from basic chain health indicators to detailed validator performance and wallet balances. This comprehensive monitoring helps ensure the reliability and security of blockchain operations.

Key Features

  • Multi-Chain Monitoring - Track metrics from multiple Cosmos-based blockchains with a single instance.
  • Prometheus Compatible - Exposes metrics in Prometheus format for easy integration with monitoring systems.
  • Validator Performance Metrics - Monitor validator voting power, commission, and uptime across chains.
  • Wallet Balance Tracking - Track balances for specified wallet addresses on monitored chains.
  • Chain Health Indicators - Monitor block heights, time between blocks, and network parameters.
  • Governance Monitoring - Track proposal status, voting periods, and participation rates.
  • Flexible Configuration - Easily configure which chains and metrics to monitor via a simple configuration file.

Installation

Install Orbit Metrics from GitHub:

git clone https://github.com/ChainTools-Tech/orbit_metrics
cd orbit_metrics
python -m pip install -e .

# Or install directly from PyPI
pip install orbit-metrics

Requirements

  • Python 3.8 or higher
  • prometheus_client
  • requests
  • PyYAML
  • Access to RPC/REST endpoints for target blockchains

Usage

Configure Orbit Metrics and start the metrics server:

# Create a configuration file (config.yaml)

# Start the metrics server
orbit-metrics --config config.yaml

# Specify custom port (default is 8000)
orbit-metrics --config config.yaml --port 9090

# Run in verbose mode for debugging
orbit-metrics --config config.yaml --verbose

Configuration

Create a YAML configuration file to specify which chains and metrics to monitor:

chains:
  juno:
    name: "Juno Network"
    rpc_endpoint: "https://rpc.juno.chaintools.tech"
    rest_endpoint: "https://rest.juno.chaintools.tech"
    denom: "ujuno"
    exponent: 6
    validators:
      - address: "junovaloper1dru5985k4n5q369rxeqfdsjl8ezutch8mc6nx9"
        name: "ChainTools"
    wallets:
      - address: "juno1abc..."
        name: "Treasury"
      - address: "juno1xyz..."
        name: "Operations"
  osmosis:
    name: "Osmosis"
    rpc_endpoint: "https://rpc.osmosis.zone"
    rest_endpoint: "https://rest.osmosis.zone"
    denom: "uosmo"
    exponent: 6

settings:
  update_interval: 60  # seconds
  metrics:
    chain_height: true
    validators: true
    proposals: true
    wallets: true

Available Metrics

Orbit Metrics collects and exposes the following metrics:

Chain Metrics

  • cosmos_chain_height - Current block height of the chain
  • cosmos_chain_block_time - Time in seconds between blocks
  • cosmos_chain_total_validators - Total number of validators
  • cosmos_chain_voting_power - Total voting power in the network
  • cosmos_chain_inflation - Current inflation rate

Validator Metrics

  • cosmos_validator_voting_power - Voting power of a specific validator
  • cosmos_validator_commission - Commission rate of a validator
  • cosmos_validator_uptime - Uptime percentage in the last 100 blocks
  • cosmos_validator_jailed - Whether a validator is jailed (1) or not (0)
  • cosmos_validator_tokens - Number of tokens bonded to a validator

Wallet Metrics

  • cosmos_wallet_balance - Balance of a specific wallet address
  • cosmos_wallet_delegated - Total amount delegated to validators
  • cosmos_wallet_rewards - Available rewards to claim
  • cosmos_wallet_unbonding - Amount currently unbonding

Governance Metrics

  • cosmos_governance_proposals - Number of active governance proposals
  • cosmos_governance_proposal_status - Status of a specific proposal
  • cosmos_governance_voting_period - Time remaining in the voting period
  • cosmos_governance_deposit - Current deposit amount for a proposal

Prometheus Integration

Orbit Metrics is designed to work seamlessly with Prometheus for monitoring and alerting. Here's how to configure Prometheus to scrape metrics:

Prometheus Configuration

scrape_configs:
  - job_name: "orbit_metrics"
    scrape_interval: 1m
    static_configs:
      - targets: ["localhost:8000"]
    metrics_path: "/metrics"
    scheme: "http"

Grafana Dashboard

You can visualize Orbit Metrics data using Grafana. A sample dashboard configuration is available in the repository:

Orbit Metrics Grafana Dashboard

Alert Rules

Sample Prometheus alert rules for monitoring critical metrics:

groups:
- name: cosmos-alerts
  rules:
  - alert: ChainHeightStalled
    expr: rate(cosmos_chain_height[10m]) == 0
    for: 5m
    labels:
      severity: critical
    annotations:
      summary: "Chain height not increasing"
      description: "The chain height for {{ $labels.chain }} has not increased in the last 5 minutes"

  - alert: ValidatorJailed
    expr: cosmos_validator_jailed == 1
    for: 1m
    labels:
      severity: critical
    annotations:
      summary: "Validator jailed"
      description: "Validator {{ $labels.validator }} on {{ $labels.chain }} is jailed"

Related Resources