metrics

Extremely fast and lightweight package for recording and exporting metrics in Prometheus exposition format.

Heavily inspired and based on VictoriaMetrics/metrics.

import "go.withmatt.com/metrics"

Features

• Very fast, very few allocations. Really.
• Optional expiring of unobserved metrics (TTL support)
• HTTP exporter
• Built-in runtime metrics collectors
• Easy Prometheus-like API
• No dependencies

Behavior Notes

Duplicate Registration: Registering the same metric name twice will panic. This is intentional to catch programming errors early during development.

TTL/Expiration: Metrics created through SetVec with a TTL will automatically expire if not accessed. See TTL example.

Quick Start

import (
	"net/http"
	"go.withmatt.com/metrics"
	"go.withmatt.com/metrics/promhttp"
)

func main() {
	// exposes Go and process runtime metrics
	metrics.RegisterDefaultCollectors()

	// create a new uint64 counter "foo" with the tag a=b
	// This will emit:
	//   foo{a="b"} 1
	c := metrics.NewUint64("foo", "a", "b")
	c.Inc()

	mux := http.NewServeMux()
	mux.Handle("/metrics", promhttp.Handler())
	panic(http.ListenAndServe("127.0.0.1:9091", mux))
}

Metric Types

• Counters (uint64/int64/float64) - Monotonically increasing values (e.g., request count, bytes sent)
• Gauges (uint64/int64/float64) - Values that can increase or decrease (e.g., memory usage, active connections)
• Histograms
  • Prometheus-like (le label style)
  • VictoriaMetrics-like (vmrange label style)

Counter vs Gauge

While this library allows both counter and gauge types to increment/decrement, you should follow Prometheus semantics:

• Use Counters for values that only increase (resets to 0 on restart). Prometheus queries use rate() and increase() functions.
• Use Gauges for current measurements that can go up or down. Despite the naming, Uint64/Int64/Float64 types can be used as gauges.

Performance

• mattware = this library
• vm = github.com/VictoriaMetrics/metrics
• prom = github.com/prometheus/client_golang/prometheus

Updating metrics

Increment a counter through UintVec.WithLabelValue API

• VM/metrics doesn't support this API natively, and their pattern for this is highly discouraged.

Update Prometheus-like histogram (le label style)

• VM/metrics does not support this.

Update VictoriaMetrics-like histogram (vmrange label style)

• Prom client does not support this.

Exporting metrics

Exporting 10,000 counters

Exporting 100 Prometheus-like histograms, with 100,000 observations each

Exporting 100 VictoriaMetrics-like histograms, with 100,000 observations each