{"id":13562310,"url":"https://github.com/QuokkaStake/cosmos-validators-exporter","last_synced_at":"2025-04-03T18:33:21.395Z","repository":{"id":50464742,"uuid":"518783140","full_name":"QuokkaStake/cosmos-validators-exporter","owner":"QuokkaStake","description":"A Prometheus exporter to fetch data about your validators in Cosmos-based blockchains.","archived":false,"fork":false,"pushed_at":"2025-01-07T17:34:05.000Z","size":3083,"stargazers_count":15,"open_issues_count":0,"forks_count":14,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T08:01:49.629Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/QuokkaStake.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2022-07-28T09:31:18.000Z","updated_at":"2025-03-27T10:15:47.000Z","dependencies_parsed_at":"2024-01-24T04:12:15.461Z","dependency_job_id":"4b9e14ae-52e4-4ac7-a385-bd8634e5267e","html_url":"https://github.com/QuokkaStake/cosmos-validators-exporter","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuokkaStake%2Fcosmos-validators-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuokkaStake%2Fcosmos-validators-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuokkaStake%2Fcosmos-validators-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/QuokkaStake%2Fcosmos-validators-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/QuokkaStake","download_url":"https://codeload.github.com/QuokkaStake/cosmos-validators-exporter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247057009,"owners_count":20876495,"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","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":"2024-08-01T13:01:07.014Z","updated_at":"2025-04-03T18:33:16.370Z","avatar_url":"https://github.com/QuokkaStake.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# cosmos-validators-exporter\n\n![Latest release](https://img.shields.io/github/v/release/QuokkaStake/cosmos-validators-exporter)\n[![Actions Status](https://github.com/QuokkaStake/cosmos-validators-exporter/workflows/test/badge.svg)](https://github.com/QuokkaStake/cosmos-validators-exporter/actions)\n[![codecov](https://codecov.io/gh/QuokkaStake/cosmos-validators-exporter/graph/badge.svg?token=WALLM02IEC)](https://codecov.io/gh/QuokkaStake/cosmos-validators-exporter)\n\ncosmos-validators-exporter is a Prometheus scraper that fetches validators stats from an LCD server\nexposed by a fullnode.\n\n## What can I use it for?\n\nYou can use it for building a validator(s) dashboard(s) to visualize your validators metrics\n(like total staked amount, delegators count, etc.) as well as building alerts for your validators' metrics\n(like validator status/ranking/total staked amount/etc.)\n\nHere's an example of the dashboard we're using in production:\n\n![Validators dashboard](https://raw.githubusercontent.com/QuokkaStake/cosmos-validators-exporter/master/images/01.png)\n\n## How can I set it up?\n\nFirst, you need to download the latest release from [the releases page](https://github.com/QuokkaStake/cosmos-validators-exporter/releases/).\nAfter that, you should unzip it, and you are ready to go:\n\n```sh\nwget \u003cthe link from the releases page\u003e\ntar xvfz \u003cfilename you just downloaded\u003e\n./cosmos-validators-exporter\n```\n\nAlternatively, you can build from source:\n```sh\ngit clone https://github.com/QuokkaStake/cosmos-validators-exporter\ncd cosmos-validators-exporter\n# This will produce a binary at ./cosmos-validators-exporter.\nmake build\n# This will produce a binary at $GOPATH/bin/cosmos-validators-exporter.\nmake install\n```\n\nTo run it detached, you need to run it as a systemd service. First, we have to copy the file to the system apps folder:\n\n```sh\nsudo cp ./cosmos-validators-exporter /usr/bin\n```\n\nThen we need to create a systemd service for our app:\n\n```sh\nsudo nano /etc/systemd/system/cosmos-validators-exporter.service\n```\n\nYou can use this template (change the user to whatever user you want this to be executed from.\nIt's advised to create a separate user for that instead of running it from root):\n\n```\n[Unit]\nDescription=Cosmos Validators Exporter\nAfter=network-online.target\n\n[Service]\nUser=\u003cusername\u003e\nTimeoutStartSec=0\nCPUWeight=95\nIOWeight=95\nExecStart=cosmos-validators-exporter --config \u003cpath to config\u003e\nRestart=always\nRestartSec=2\nLimitNOFILE=800000\nKillSignal=SIGTERM\n\n[Install]\nWantedBy=multi-user.target\n```\n\nThen we'll add this service to autostart and run it:\n\n```sh\nsudo systemctl daemon-reload # reflect the systemd file change\nsudo systemctl enable cosmos-validators-exporter # enable the scraper to run on system startup\nsudo systemctl start cosmos-validators-exporter # start it\nsudo systemctl status cosmos-validators-exporter # validate it's running\n```\n\nIf you need to, you can also see the logs of the process:\n\n```sh\nsudo journalctl -u cosmos-validators-exporter -f --output cat\n```\n\n## How can I scrape data from it?\n\nHere's the example of the Prometheus config you can use for scraping data:\n\n```yaml\nscrape-configs:\n  - job_name:       'cosmos-validators-exporter'\n    scrape_interval: 60s\n    scrape_timeout: 60s\n    static_configs:\n      - targets:\n        - localhost:9560 # replace localhost with scraper IP if it's on the other host\n```\n\nThen restart Prometheus and you're good to go!\n\n*Important: consider setting quite big intervals/timeouts, both in app config and in Prometheus config.\nThis is due to some requests taking a lot of time, and with a shorter timeout there's a chance\nthe whole scrape request will time out. If you face scrape errors, consider increasing the timeout.*\n\nAll the metrics provided by cosmos-validators-exporter have the `cosmos_validators_exporter_` as a prefix.\nFor the full list of metrics, try running `curl localhost:9560/metrics` (or your host/port, if it's non-standard)\nand see the list of metrics there.\n\n## Queries examples\n\nWhen developing, we aimed to only return metrics that are required, and avoid creating metrics that can be computed\non Grafana/Prometheus side. This decreases the amount of time series that this exporter will return, but will make\nwriting queries more complex. Here are some examples of queries that we consider useful:\n\n- `count(cosmos_validators_exporter_info)` - number of validators monitored\n- `sum((cosmos_validators_exporter_total_delegations) * on (chain) group_left(denom) cosmos_validators_exporter_base_denom / on (chain, denom) cosmos_validators_exporter_denom_coefficient * on (chain, denom) cosmos_validators_exporter_price)` - total delegated tokens in $\n- `sum(cosmos_validators_exporter_delegations_count)` - total delegators count\n- `cosmos_validators_exporter_total_delegations / on (chain) cosmos_validators_exporter_tokens_bonded_total` - voting power percent of your validator\n- `1 - (cosmos_validators_exporter_missed_blocks / on (chain) cosmos_validators_exporter_missed_blocks_window)` - validator's uptime in %\n\n## How can I configure it?\n\nAll configuration is done via the .toml config file, which is passed to the application\nvia the `--config` app parameter. Check `config.example.toml` for a config reference.\n\n## How can I contribute?\n\nBug reports and feature requests are always welcome! If you want to contribute, feel free to open issues or PRs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuokkaStake%2Fcosmos-validators-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FQuokkaStake%2Fcosmos-validators-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FQuokkaStake%2Fcosmos-validators-exporter/lists"}