{"id":30105100,"url":"https://github.com/forbole/cosmos-exporter","last_synced_at":"2026-01-05T21:16:50.367Z","repository":{"id":103098171,"uuid":"472321014","full_name":"forbole/cosmos-exporter","owner":"forbole","description":null,"archived":false,"fork":false,"pushed_at":"2025-04-13T15:13:32.000Z","size":448,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-13T15:25:23.545Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/forbole.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-03-21T12:10:26.000Z","updated_at":"2022-03-21T12:13:42.000Z","dependencies_parsed_at":"2023-09-08T19:15:57.145Z","dependency_job_id":null,"html_url":"https://github.com/forbole/cosmos-exporter","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/forbole/cosmos-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbole%2Fcosmos-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbole%2Fcosmos-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbole%2Fcosmos-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbole%2Fcosmos-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/forbole","download_url":"https://codeload.github.com/forbole/cosmos-exporter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/forbole%2Fcosmos-exporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269654380,"owners_count":24454321,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-09T02:00:10.424Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-09T23:46:00.140Z","updated_at":"2026-01-05T21:16:50.361Z","avatar_url":"https://github.com/forbole.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cosmos-exporter\n1. `make install`\n2. `cosmos-expoter start --home /path/to/config/file/config.yaml`\n\n## Compatibility\nThis version has been upgraded to support:\n- Cosmos SDK v0.50.x\n- CometBFT v0.38+\n\nThe exporter should still work with older chains, but is optimized for newer versions.\n\n### Backward Compatibility\nThe exporter maintains backward compatibility with:\n- Older Cosmos SDK versions (v0.45.x and earlier)\n- Tendermint nodes (pre-CometBFT)\n\nThis allows for a smooth upgrade path, as the same exporter can be used across different chain versions in your infrastructure.\n\n## Runtime Resilience \u0026 Failover\nThe exporter now supports automatic runtime failover across multiple gRPC and RPC endpoints.\n\n### Endpoint Sources\n1. Config file (`node.grpc`, `node.rpc`)\n2. Chain Registry (when `--chain-name \u003cname\u003e` is supplied and a local chain-registry clone is present)\n\nAll discovered endpoints are deduplicated; gRPC and RPC each maintain their own candidate list.\n\n### Rotation Logic\nThe exporter tracks consecutive errors for gRPC and RPC:\n- On every failed gRPC query (e.g. governance proposals, votes), an error streak counter increments.\n- When the streak reaches the configured threshold, the exporter rotates to the next gRPC endpoint, redials, and resets the streak.\n- RPC rotation (currently used for chain ID refresh logic) follows the same pattern.\n\n### Environment Variables (Threshold Overrides)\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `COSMOS_EXPORTER_MAX_GRPC_ERRORS` | Consecutive gRPC errors before rotating | `3` |\n| `COSMOS_EXPORTER_MAX_RPC_ERRORS`  | Consecutive RPC errors before rotating  | `3` |\n\nSet to `1` for quick testing (forces rotation on first error).\n\n### CLI Flags\n| Flag | Description | Default |\n|------|-------------|---------|\n| `--chain-name` | Enable chain-registry endpoint discovery | (empty) |\n| `--chain-registry-path` | Path to local chain-registry clone | `./chain-registry` |\n| `--listen-address` | Override listen port/address (e.g. `:26647`) | value from config `port` |\n| `--scrape-interval` | Scrape interval (`30s`, `1m`, `5m`, etc.) | `10m` |\n\n### Example: Fast Rotation Test\n```bash\nexport COSMOS_EXPORTER_MAX_GRPC_ERRORS=1\nexport COSMOS_EXPORTER_MAX_RPC_ERRORS=2\n./build/cosmos_exporter start \\\n  --home ~/.cosmos-exporter \\\n  --chain-name xpla \\\n  --chain-registry-path ./chain-registry \\\n  --listen-address :26647 \\\n  --scrape-interval 30s\n```\n\nExpected logs when an endpoint is flaky:\n```\n[gRPC] error streak=1/1 err=...\n[gRPC] rotating endpoint error_streak=1 old=grpc.old.endpoint new=grpc.new.endpoint\n```\n\nIf only one endpoint exists, rotation will not occur (streak logs appear but no switch). Add a second endpoint via config or chain registry to test.\n\n### Operational Tips\n- Use a longer interval (e.g. `--scrape-interval 5m`) in production to reduce load.\n- Keep thresholds \u003e1 in production to avoid rotating on transient blips.\n- Monitor logs (or extend with Prometheus metrics) to observe rotation behavior.\n- You can pin a single endpoint by setting thresholds very high (e.g. `COSMOS_EXPORTER_MAX_GRPC_ERRORS=999999`).\n\n### Future Improvements (optional)\nPotential follow-ups you can implement or request:\n- Prometheus counters for rotation events.\n- Readiness/health endpoint.\n- CLI flags for thresholds instead of env vars.\n- Extending rotation triggers to all collectors (currently governance-focused for gRPC error streaks).\n\n# Config file template\n```yaml\ndelegator_addresses: \n  - \"delegator_address\"\nvalidator_address: \"validator_address\"\nport: \":9092\"\ndenom_metadata:\n display_denom: \"atom\"\n base_denom: \"uatom\"\n exponent: 6\nnode:\n rpc: \"http://localhost:26657\"\n grpc: \"localhost:9090\"\n secure: false\n```\n\n## Chain Registry Submodule\nThis repository uses the official `cosmos/chain-registry` as a Git submodule (directory: `chain-registry`).\n\n### First Clone\n```bash\ngit clone \u003cyour-fork-or-repo\u003e\ncd cosmos-exporter\ngit submodule update --init --recursive\n```\n\n### Update to Latest Registry\n```bash\ngit submodule update --remote --merge chain-registry\ngit commit -am \"Update chain-registry submodule\"\n```\n\n### Shallow Clone (already configured)\nThe submodule was added with `--depth 1` to save time/space. To deepen later:\n```bash\ncd chain-registry\ngit fetch --unshallow || true\n```\n\n### Sparse Checkout (optional)\nIf you only need a few chains (example: xpla, cosmoshub):\n```bash\ncd chain-registry\ngit sparse-checkout init --cone\ngit sparse-checkout set xpla cosmoshub\n```\n\n### Removing the Submodule (if ever needed)\n```bash\ngit submodule deinit -f chain-registry\ngit rm -f chain-registry\nrm -rf .git/modules/chain-registry\ngit commit -m \"Remove chain-registry submodule\"\n```\n\n## Systemd Service Example\nCreate `/etc/systemd/system/cosmos-exporter-xpla.service`:\n```ini\n[Unit]\nDescription=Cosmos Exporter (XPLA)\nAfter=network-online.target\nWants=network-online.target\n\n[Service]\nType=simple\nWorkingDirectory=/opt/cosmos-exporter\nExecStart=/opt/cosmos-exporter/build/cosmos_exporter start \\\\\n  --home /opt/cosmos-exporter/.xpla-exporter \\\\\n  --chain-name xpla \\\\\n  --chain-registry-path /opt/cosmos-exporter/chain-registry \\\\\n  --listen-address :26647 \\\\\n  --scrape-interval 1m\nEnvironment=COSMOS_EXPORTER_MAX_GRPC_ERRORS=3\nEnvironment=COSMOS_EXPORTER_MAX_RPC_ERRORS=3\nRestart=on-failure\nRestartSec=5\nUser=cosmos\nGroup=cosmos\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThen:\n```bash\nsudo systemctl daemon-reload\nsudo systemctl enable --now cosmos-exporter-xpla\nsudo systemctl status cosmos-exporter-xpla --no-pager\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbole%2Fcosmos-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fforbole%2Fcosmos-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fforbole%2Fcosmos-exporter/lists"}