Prometheus Aggregation Gateway

This service accepts Prometheus metrics, validates, aggregates, and exposes them ready for scraping in /metrics endpoint¹².

• consume batch by JSON http body
• consume one by URL Path or Query (hit counter)
• no dependencies
• 500LOC
• 100% coverage
• defensive validation
• histogram³
• summary via t-digest⁴
• User-Agent, Accept-Language

Bring it to your own http server

func main() {
	var config pag.PromAggGatewayServerConfig
	configBytes, _ := os.ReadFile(os.Getenv("PAG_CONFIG_PATH"))
	if err := yaml.Unmarshal(configBytes, &config); err != nil {
		log.Fatal(err)
	}

	s := pag.NewPromAggGatewayServer(config)

	http.HandleFunc("GET /hit", s.ConsumeMetricFromURLQuery)
	http.HandleFunc("POST /metrics", s.ConsumeMetrics)
	http.HandleFunc("GET /metrics", s.GetMetrics)

	log.Fatal(http.ListenAndServe(":8080", nil))
}

ADR

• 2025-04-04 URL Query consumes only single metric for simple API (histograms break down into multiple metric names, hence not accepted in URL Query)
• 2024-12-02 not using Prometheus Pushgateway, because it does not aggregate metrics
• 2024-12-02 not using zapier prom aggregation gateway, because: too many 3rd party dependencies (e.g. gin, cobra); no defensive validation;

Footnotes

1. https://prometheus.io/docs/practices/naming/ ↩

2. https://github.com/prometheus/docs/blob/main/content/docs/instrumenting/exposition_formats.md ↩

3. https://prometheus.io/docs/practices/histograms/ ↩

4. https://github.com/ndx-technologies/tdigest ↩