{"id":13813538,"url":"https://github.com/wi1dcard/v2ray-exporter","last_synced_at":"2025-08-12T00:05:40.181Z","repository":{"id":45297905,"uuid":"232474306","full_name":"wi1dcard/v2ray-exporter","owner":"wi1dcard","description":"🧭 Prometheus exporter for V2Ray and V2Fly metrics, with a simple Grafana dashboard.","archived":false,"fork":false,"pushed_at":"2024-03-30T12:26:50.000Z","size":56,"stargazers_count":127,"open_issues_count":4,"forks_count":33,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-07-05T17:08:38.527Z","etag":null,"topics":["grafana","prometheus-exporter","v2fly","v2ray"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wi1dcard.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}},"created_at":"2020-01-08T04:01:58.000Z","updated_at":"2025-06-02T09:08:38.000Z","dependencies_parsed_at":"2024-03-30T13:44:33.465Z","dependency_job_id":null,"html_url":"https://github.com/wi1dcard/v2ray-exporter","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/wi1dcard/v2ray-exporter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Fv2ray-exporter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Fv2ray-exporter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Fv2ray-exporter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Fv2ray-exporter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wi1dcard","download_url":"https://codeload.github.com/wi1dcard/v2ray-exporter/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wi1dcard%2Fv2ray-exporter/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":269976766,"owners_count":24506465,"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-11T02:00:10.019Z","response_time":75,"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":["grafana","prometheus-exporter","v2fly","v2ray"],"created_at":"2024-08-04T04:01:20.835Z","updated_at":"2025-08-12T00:05:40.158Z","avatar_url":"https://github.com/wi1dcard.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# V2Ray Exporter\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/wi1dcard/v2ray-exporter)][goreportcard]\n[![Build Status](https://app.travis-ci.com/wi1dcard/v2ray-exporter.svg?branch=master)][build-status]\n\nAn exporter that collect V2Ray metrics over its [Stats API][stats-api] and export them to Prometheus.\n\n- [V2Ray Exporter](#v2ray-exporter)\n  - [Quick Start](#quick-start)\n    - [Binaries](#binaries)\n    - [Third-party Packages](#third-party-packages)\n    - [Docker (Recommended)](#docker-recommended)\n    - [Grafana Dashboard](#grafana-dashboard)\n  - [Tutorial](#tutorial)\n  - [Digging Deeper](#digging-deeper)\n  - [TODOs](#todos)\n  - [Special Thanks](#special-thanks)\n  - [License](#license)\n\n![][grafana-screenshot]\n\n[stats-api]: https://www.v2ray.com/chapter_02/stats.html\n[goreportcard]: https://goreportcard.com/report/github.com/wi1dcard/v2ray-exporter\n[grafana-screenshot]: https://i.loli.net/2020/06/12/KzjOnyu93VEIPiW.png\n[build-status]: https://app.travis-ci.com/github/wi1dcard/v2ray-exporter\n\n## Quick Start\n\n### Binaries\n\nThe latest binaries are made available on GitHub [releases][github-releases] page:\n\n```bash\nwget -O /tmp/v2ray-exporter https://github.com/wi1dcard/v2ray-exporter/releases/latest/download/v2ray-exporter_linux_amd64\nmv /tmp/v2ray-exporter /usr/local/bin/v2ray-exporter\nchmod +x /usr/local/bin/v2ray-exporter\n```\n\n### Third-party Packages\n\n- Arch Linux (@unknowndev233): \u003chttps://aur.archlinux.org/packages/v2ray-exporter\u003e\n\n### Docker (Recommended)\n\nYou can also find the docker images built automatically by CI from [Docker Hub](https://hub.docker.com/r/wi1dcard/v2ray-exporter). The images are made for multi-arch. You can run it from your Raspberry Pi or any other ARM, ARM64 devices without changing the image name:\n\n```bash\ndocker run --rm -it wi1dcard/v2ray-exporter:\u003cTAG\u003e\n```\n\nPlease note that `latest` tag is not available. Use `master` instead if you want the latest build of master branch.\n\n### Grafana Dashboard\n\nA simple Grafana dashboard is also available [here][grafana-dashboard]. Please refer to the [Grafana docs][grafana-importing-dashboard] to get the steps of importing dashboards from JSON files.\n\nNote that the dashboard on [grafana.com][grafana-dashboard-grafana-dot-com] may not be the latest version, please consider downloading the dashboard JSON from the link above.\n\n## Tutorial\n\nBefore we start, let's assume you have already set up Prometheus and Grafana.\n\nFirstly, you will need to make sure the API and statistics related features have been enabled in your V2Ray config file. For example:\n\n```json\n{\n    \"stats\": {},\n    \"api\": {\n        \"tag\": \"api\",\n        \"services\": [\n            \"StatsService\"\n        ]\n    },\n    \"policy\": {\n        \"levels\": {\n            \"0\": {\n                \"statsUserUplink\": true,\n                \"statsUserDownlink\": true\n            }\n        },\n        \"system\": {\n            \"statsInboundUplink\": true,\n            \"statsInboundDownlink\": true,\n            \"statsOutboundUplink\": true,\n            \"statsOutboundDownlink\": true\n        }\n    },\n    \"inbounds\": [\n        {\n            \"tag\": \"tcp\",\n            \"port\": 12345,\n            \"protocol\": \"vmess\",\n            \"settings\": {\n                \"clients\": [\n                    {\n                        \"email\": \"foo@example.com\",\n                        \"id\": \"e731f153-4f31-49d3-9e8f-ff8f396135ef\",\n                        \"level\": 0,\n                        \"alterId\": 4\n                    },\n                    {\n                        \"email\": \"bar@example.com\",\n                        \"id\": \"e731f153-4f31-49d3-9e8f-ff8f396135ee\",\n                        \"level\": 0,\n                        \"alterId\": 4\n                    }\n                ]\n            }\n        },\n        {\n            \"tag\": \"api\",\n            \"listen\": \"127.0.0.1\",\n            \"port\": 54321,\n            \"protocol\": \"dokodemo-door\",\n            \"settings\": {\n                \"address\": \"127.0.0.1\"\n            }\n        }\n    ],\n    \"outbounds\": [\n        {\n            \"protocol\": \"freedom\",\n            \"settings\": {}\n        }\n    ],\n    \"routing\": {\n        \"rules\": [\n            {\n                \"inboundTag\": [\n                    \"api\"\n                ],\n                \"outboundTag\": \"api\",\n                \"type\": \"field\"\n            }\n        ]\n    }\n}\n```\n\nAs you can see, we opened two inbounds in the configuration above. The first inbound accepts VMess connections from user `foo@example.com` and `bar@example.com`, and the second one listens port 54321 on localhost and handles the API calls, which is the endpoint that the exporter scrapes. If you'd like to run V2Ray and exporter on different machines, consider use `0.0.0.0` instead of `127.0.0.1` and be careful with the security risks.\n\nAdditionally, you should also enable `stats`, `api`, and `policy` settings, and setup proper routing rules in order to get traffic statistics works. For more information, please visit [The Beginner's Guide of V2Ray][v2ray-beginners-guide].\n\nThe next step is to start the exporter:\n\n```bash\nv2ray-exporter --v2ray-endpoint \"127.0.0.1:54321\"\n## Or\ndocker run --rm -d wi1dcard/v2ray-exporter:master --v2ray-endpoint \"127.0.0.1:54321\"\n```\n\nThe logs signifies that the exporter started to listening on the default address (`:9550`).\n\n```plain\nV2Ray Exporter master-39eb972 (built 2020-04-05T05:32:01Z)\ntime=\"2020-05-11T06:18:09Z\" level=info msg=\"Server is ready to handle incoming scrape requests.\"\n```\n\nUse `--listen` option if you'd like to changing the listen address or port. You can now open `http://IP:9550` in your browser:\n\n![browser.png][browser-screenshot]\n\nClick the `Scrape V2Ray Metrics` and the exporter will expose all metrics including V2Ray runtime and statistics data in the Prometheus metrics format, for example:\n\n```\n...\n# HELP v2ray_up Indicate scrape succeeded or not\n# TYPE v2ray_up gauge\nv2ray_up 1\n# HELP v2ray_uptime_seconds V2Ray uptime in seconds\n# TYPE v2ray_uptime_seconds gauge\nv2ray_uptime_seconds 150624\n...\n```\n\nIf `v2ray_up 1` doesn't exist in the response, that means the scrape was failed, please check out the logs (STDOUT or STDERR) of V2Ray Exporter for more detailed information.\n\nWe have the metrics exposed. Now let Prometheus scrapes these data points and visualize them with Grafana. Here is an example Promtheus configuration:\n\n```yaml\nglobal:\n  scrape_interval: 15s\n  scrape_timeout: 5s\n\nscrape_configs:\n  - job_name: v2ray\n    metrics_path: /scrape\n    static_configs:\n      - targets: [IP:9550]\n```\n\nTo learn more about Prometheus, please visit the [official docs][prometheus-docs].\n\n## Digging Deeper\n\nThe exporter doesn't retain the original metric names from V2Ray intentionally. You may find out why in the [comments][explaination-of-metric-names].\n\nFor users who do not really care about the internal changes, but only need a mapping table, here it is:\n\n| Runtime Metric   | Exposed Metric                     |\n| :--------------- | :--------------------------------- |\n| `uptime`         | `v2ray_uptime_seconds`             |\n| `num_goroutine`  | `v2ray_goroutines`                 |\n| `alloc`          | `v2ray_memstats_alloc_bytes`       |\n| `total_alloc`    | `v2ray_memstats_alloc_bytes_total` |\n| `sys`            | `v2ray_memstats_sys_bytes`         |\n| `mallocs`        | `v2ray_memstats_mallocs_total`     |\n| `frees`          | `v2ray_memstats_frees_total`       |\n| `live_objects`   | Removed. See the appendix below.   |\n| `num_gc`         | `v2ray_memstats_num_gc`            |\n| `pause_total_ns` | `v2ray_memstats_pause_total_ns`    |\n\n| Statistic Metric                          | Exposed Metric                                                              |\n| :---------------------------------------- | :-------------------------------------------------------------------------- |\n| `inbound\u003e\u003e\u003etag-name\u003e\u003e\u003etraffic\u003e\u003e\u003euplink`   | `v2ray_traffic_uplink_bytes_total{dimension=\"inbound\",target=\"tag-name\"}`   |\n| `inbound\u003e\u003e\u003etag-name\u003e\u003e\u003etraffic\u003e\u003e\u003edownlink` | `v2ray_traffic_downlink_bytes_total{dimension=\"inbound\",target=\"tag-name\"}` |\n| `outbound\u003e\u003e\u003etag-name\u003e\u003e\u003etraffic\u003e\u003e\u003euplink`   | `v2ray_traffic_uplink_bytes_total{dimension=\"outbound\",target=\"tag-name\"}`   |\n| `outbound\u003e\u003e\u003etag-name\u003e\u003e\u003etraffic\u003e\u003e\u003edownlink` | `v2ray_traffic_downlink_bytes_total{dimension=\"outbound\",target=\"tag-name\"}` |\n| `user\u003e\u003e\u003euser-email\u003e\u003etraffic\u003e\u003e\u003euplink`     | `v2ray_traffic_uplink_bytes_total{dimension=\"user\",target=\"user-email\"}`    |\n| `user\u003e\u003e\u003euser-email\u003e\u003e\u003etraffic\u003e\u003e\u003edownlink`  | `v2ray_traffic_downlink_bytes_total{dimension=\"user\",target=\"user-email\"}`  |\n| ...                                       | ...                                                                         |\n\n- The value of `live_objects` can be calculated by `memstats_mallocs_total - memstats_frees_total`.\n\n## TODOs\n\n- GitHub Action\n\n## Special Thanks\n\n- \u003chttps://github.com/schweikert/fping-exporter\u003e\n- \u003chttps://github.com/oliver006/redis_exporter\u003e\n- \u003chttps://github.com/roboll/helmfile\u003e\n\n## License\n\nMIT\n\n[github-releases]: https://github.com/wi1dcard/v2ray-exporter/releases\n[v2ray-beginners-guide]: https://guide.v2fly.org/en_US/advanced/traffic.html\n[browser-screenshot]: https://i.loli.net/2020/01/11/ZVtNEU8iqMrFGKm.png\n[prometheus-docs]: https://prometheus.io/docs/prometheus/latest/configuration/configuration/\n[grafana-dashboard]: ./dashboard.json\n[grafana-dashboard-grafana-dot-com]: https://grafana.com/grafana/dashboards/11545\n[grafana-importing-dashboard]: https://grafana.com/docs/grafana/latest/reference/export_import/#importing-a-dashboard\n[explaination-of-metric-names]: https://github.com/wi1dcard/v2ray-exporter/blob/110e82dfefb1b51f4da3966ddd1945b5d0dac203/exporter.go#L134\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwi1dcard%2Fv2ray-exporter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwi1dcard%2Fv2ray-exporter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwi1dcard%2Fv2ray-exporter/lists"}