Export cache stats as Prometheus metrics

[Baliedge]

Based off of: https://github.com/udhos/groupcache_exporter by @udhos.

Synopsis

The groupcache_exporter repo contains a great solution for exporting groupcache statistics as Prometheus metrics. But, this requires Golang 1.23 to satisfy support for multiple implementations of groupcache. The Mailgun groupcache implementation does not have this requirement and prefers to stay on stable Golang 1.22.

Features

• This variant contains only support for Mailgun's groupcache and removed extraneous logic related to other implementations.
• Golang set to 1.22 for maximum compatibility at time of release.
• The exporter discovers groups at scrape-time. No need to pass group references.

Usage

The exporter need only be configured once in your application. Registering the exporter again (with the same namespace) will create a metric name collision in Prometheus. All groupcache groups will be exported automatically, even those created after setting up the exporter.

Example:

import (
	"github.com/mailgun/groupcache/v2"
	"github.com/mailgun/groupcache/v2/promexporter"
	"github.com/prometheus/client_golang/prometheus"
)

// ...

collector := promexporter.NewExporter()
prometheus.MustRegister(collector)

group := groupcache.NewGroup("mygroup")

Optionally pass one or more variadic arguments to NewExporter():

• promexporter.WithNamespace("prefix"): Add <namespace>_ prefix to all metric names.
• promexporter.WithLabels(labels): Add static labels to exported metrics.
• promexporter.WithGroups(fn): Set callback function to dynamically retrieve groupcache groups to export. Overrides default that discovers all groups.

Metrics

Exported from groupcache's CacheStats()

• groupcache_cache_bytes{group,type="main|hot"}: Gauge of current bytes in use
• groupcache_cache_evictions_nonexpired_total{group,type="main|hot"}: Count of cache evictions for non-expired keys due to memory full
• groupcache_cache_evictions_total{group,type="main|hot"}: Count of cache evictions
• groupcache_cache_gets_total{group,type="main|hot"}: Count of cache gets
• groupcache_cache_hits_total{group,type="main|hot"}: Count of cache hits
• groupcache_cache_items{group,type="main|hot"}: Gauge of current items in use

Exported from groupcache's Stats()

• groupcache_get_from_peers_latency_lower{group}: Represent slowest duration to request value from peers
• groupcache_gets_total{group}: Count of cache gets (including from peers, from either main or hot caches)
• groupcache_hits_total{group}: Count of cache hits (from either main or hot caches)
• groupcache_loads_deduped_total{group}: Count of loads after singleflight
• groupcache_loads_total{group}: Count of (gets - hits)
• groupcache_local_load_errs_total{group}: Count of loads from local cache that failed
• groupcache_local_loads_total{group}: Count of loads from local cache
• groupcache_peer_errors_total{group}: Count of errors from peers
• groupcache_peer_loads_total{group}: Count of non-error loads or cache hits from peers
• groupcache_server_requests_total{group}: Count of gets that came over the network from peers

Changes to Metrics from udhos Source

• groupcache_get_from_peers_latency_slowest_milliseconds -> groupcache_get_from_peers_latency_lower
  • Name matches field from groupcache stats.
  • Also changed unit to seconds as best practice for duration gauges.
• groupcache_local_load_total -> groupcache_local_loads_total

[vtopc]

prefers to stay on stable Golang 1.22

I would say it's stable already, there were a lot of minor updates - https://go.dev/doc/devel/release#go1.23.0