{"id":13561553,"url":"https://github.com/jacksontj/promxy","last_synced_at":"2025-05-13T21:12:49.497Z","repository":{"id":30031918,"uuid":"106239956","full_name":"jacksontj/promxy","owner":"jacksontj","description":"An aggregating proxy to enable HA prometheus","archived":false,"fork":false,"pushed_at":"2025-04-16T23:12:11.000Z","size":87164,"stargazers_count":1205,"open_issues_count":24,"forks_count":135,"subscribers_count":28,"default_branch":"master","last_synced_at":"2025-04-28T17:21:21.946Z","etag":null,"topics":["golang","graphing","high-availability","http","monitoring","multi-prometheus-proxy","prometheus","prometheus-infrastructure","prometheus-proxy","promql","proxy","redundancy","time-series"],"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/jacksontj.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,"zenodo":null}},"created_at":"2017-10-09T05:26:33.000Z","updated_at":"2025-04-24T06:01:10.000Z","dependencies_parsed_at":"2023-10-16T13:29:32.896Z","dependency_job_id":"c498f7b9-2cf0-409c-b52c-83adfd560abe","html_url":"https://github.com/jacksontj/promxy","commit_stats":null,"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksontj%2Fpromxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksontj%2Fpromxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksontj%2Fpromxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jacksontj%2Fpromxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jacksontj","download_url":"https://codeload.github.com/jacksontj/promxy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254029008,"owners_count":22002284,"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":["golang","graphing","high-availability","http","monitoring","multi-prometheus-proxy","prometheus","prometheus-infrastructure","prometheus-proxy","promql","proxy","redundancy","time-series"],"created_at":"2024-08-01T13:00:58.242Z","updated_at":"2025-05-13T21:12:44.484Z","avatar_url":"https://github.com/jacksontj.png","language":"Go","funding_links":[],"categories":["Go","Observability","Proxies"],"sub_categories":["Miscellaneous"],"readme":"# Promxy [![Test Actions Status](https://github.com/jacksontj/promxy/workflows/Go/badge.svg)](https://github.com/jacksontj/promxy/actions) [![GoDoc](https://godoc.org/github.com/jacksontj/promxy?status.svg)](https://godoc.org/github.com/jacksontj/promxy) [![Go Report Card](https://goreportcard.com/badge/github.com/jacksontj/promxy)](https://goreportcard.com/report/github.com/jacksontj/promxy) ![build](https://github.com/jacksontj/promxy/workflows/build/badge.svg) [![Docker Repository on Quay](https://quay.io/repository/jacksontj/promxy/status \"Docker Repository on Quay\")](https://quay.io/repository/jacksontj/promxy)\n\npronounced \"promski\" or präm-sē\n\n## High-level overview\nPromxy is a prometheus proxy that makes many shards of prometheus\nappear as a single API endpoint to the user. This significantly simplifies operations\nand use of prometheus at scale (when you have more than one prometheus host).\nPromxy delivers this unified access endpoint without requiring **any** sidecars,\ncustom-builds, or other changes to your prometheus infrastructure.\n\n## Why promxy?\n[**Detailed version**](MOTIVATION.md)\n\n**Short version**:\nPrometheus itself provides no real HA/clustering support. As such the best-practice\nis to run multiple (e.g N) hosts with the same config. Similarly prometheus has no real\nbuilt-in query federation, which means that you end up with N sources in grafana\nwhich is (1) confusing to grafana users and (2) has no support for aggregation across the sources.\nPromxy enables an HA prometheus setup by \"merging\" the data from the duplicate\nhosts (so if there is a gap in one, promxy will fill with the other). In addition\nPromxy provides a single datasource for all promql queries -- meaning your grafana\ncan have a single source and you can have globally aggregated promql queries.\n\n## Quickstart\nRelease binaries are available on the [releases](https://github.com/jacksontj/promxy/releases) page.\n\nIf you are interested in hacking on promxy (or just running your own build), you can clone and build:\n\n```\ngit clone git@github.com:jacksontj/promxy.git\ncd promxy/cmd/promxy \u0026\u0026 go build -mod=vendor -tags netgo,builtinassets\n```\n\nAn example configuration file is available in the [repo](https://github.com/jacksontj/promxy/blob/master/cmd/promxy/config.yaml).\n\nWith that configuration modified and ready, all that is left is to run promxy:\n\n```\n./promxy --config=config.yaml\n```\n\n## FAQ\n\n### What is a \"ServerGroup\"?\nA `ServerGroup` is a set of prometheus hosts configured the same. This is a common best practice\nfor prometheus infrastructure as prometheus itself doesn't support any HA/clustering. This\nallows promxy to merge data from multiple hosts in the `ServerGroup` ([all until it becomes a priority](https://github.com/jacksontj/promxy/issues/3)).\nThis allows promxy to \"fill\" in the holes in timeseries, such as the ones created when upgrading\nprometheus or rebooting the host\n\n### What versions of prometheus does promxy support?\nPromxy uses the `/v1` API of prometheus under-the-hood, meaning that promxy simply\nrequires that API to be present. Promxy has been used with as early as prom 1.7\nand as recent as 2.13. If you run into issues with any prometheus version with the `/v1`\nAPI please open up an issue.\n\n### What version of prometheus does promxy use? And what does that mean?\nPromxy is currently using a fork based on prometheus 2.24. This version isn't supremely important,\nbut it is relevant for promql features (e.g. subqueries) and sd config options.\n\n### What changes are required to my prometheus infra for promxy?\nNone. Promxy is simply an aggregating proxy that sends requests to prometheus -- meaning\nit requires no changes to your existing prometheus install.\n\n### Can I have promxy as a downstream of promxy?\nYes! Promxy simply aggregates other prometheus API endpoints together so you can definitely layer promxy.\nSimilarly you can mix prometheus API endpoints, for example you could have prometheus, promxy, and \nVictoriaMetrics all as downstreams of a promxy host -- since they all have prometheus compatible APIs.\n\n### What is query performance like with promxy?\nPromxy's goal is to be the same performance as the slowest prometheus server it\nhas to talk to. If you have a query that is significantly slower through promxy\nthan on prometheus direct please open up an issue so we can get that taken care of.\n\n**Note**: if you are running prometheus \u003c2.2 you may notice \"slow\" performance when running queries that access large amounts of data. This is due to inefficient json marshaling in prometheus. You can workaround this by configuring promxy to use the [remote_read](https://github.com/jacksontj/promxy/blob/master/pkg/servergroup/config.go#L27) API.\n\n### How does Promxy know what prometheus server to route to?\nPromxy currently does a complete scatter-gather to all configured server groups.\nThere are plans to [reduce scatter-gather queries](https://github.com/jacksontj/promxy/issues/2)\nbut in practice the current \"scatter-gather always\" implementation hasn't been a bottleneck.\n\n### How do I use alerting/recording rules in promxy?\nPromxy is simply an aggregating proxy in front of your prometheus infrastructure. As such, you can use promxy to\ncreate alerting/recording rules which will execute across your entire prometheus infrastructure. For example, if\nyou wanted to know that the global error rate was \u003c10% this would be impossible on the individual prometheus hosts\n(without federation, or re-scraping) but trivial in promxy.\n\n**Note**: recording rules in regular prometheus write to their local tsdb. Promxy has no local tsdb, so if you wish\nto use recording rules (or see the metrics from alerting rules) a [remote_write](https://github.com/jacksontj/promxy/blob/master/cmd/promxy/config.yaml#L22)\nendpoint must be defined in the promxy config (which is where it will send those metrics).\n\n### What happens when an entire ServerGroup is unavailable?\nThe default behavior in the event of a servergroup being down is to return an error. If all nodes in a servergroup\nare down the resulting data can be inaccurate (missing data, etc.) -- so we'd rather by default return an error \nthan an inaccurate value (since alerting etc. might rely on it, we don't want to hide a problem).\n\nNow with that said if you'd like to make some or all servergroups \"optional\" (meaning the errors will\nbe ignored and we'll serve the response anyways) you can do this using the [ignore_error option](https://github.com/jacksontj/promxy/blob/master/cmd/promxy/config.yaml#L86) on the servergroup.\n\n## Questions/Bugs/etc.\nFeedback is **greatly** appreciated. If you find a bug, have a feature request, or just have a general question feel free to open up an issue!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksontj%2Fpromxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjacksontj%2Fpromxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjacksontj%2Fpromxy/lists"}