Util

util/ is the catch-all for small reusable packages. Most of them are optimised primitives used on hot paths.

Path	Purpose
util/almost	Float comparison with tolerance.
util/annotations	PromQL warning/info annotations (PromQLInfo, PromQLWarning, BadBucketLabelInfo, …).
util/compression	Snappy / Zstd / None codec abstraction; used by WAL and remote write.
util/convertnhcb	Classical histogram -> NHCB conversion.
util/documentcli	The --write-documentation helper used by prometheus and promtool to emit Markdown CLI docs.
util/features	The Collector registry that backs /api/v1/features. See subsystems/util.md and the features page.
util/fmtutil	Number-formatting helpers used by templates and the API.
util/fuzzing	Fuzz target packages (run via OSS-Fuzz).
util/gate	Counting semaphore used by the engine for max-concurrent-queries.
util/httputil	Reusable HTTP middleware: CORS, compression, conntrack, gzip, logger.
util/jsonutil	Streaming JSON helpers; used by the API codec.
util/junitxml	JUnit XML emitter used by promtool test rules.
util/kahansum	Numerically stable sum (Kahan-Babuška-Neumaier).
util/logging	JSONFileLogger and a slog wrapper used for the query log and scrape failure log.
util/namevalidationutil	UTF-8 metric/label name validation for ingestion.
util/netconnlimit	Per-listener max-connections limiter.
util/notifications	The notification stream consumed by /api/v1/notifications.
util/osutil	Cross-platform file mode helpers.
util/pool	Size-class wrapper around sync.Pool for byte slices.
util/runtime	Runtime info helpers (uname, hostname, FD limits, GOMEMLIMIT).
util/runutil	RunWithCancel helper for backoff loops.
util/stats	Per-query and per-scrape statistics; basis of stats=all.
util/strutil	Sanitisation, slug-ification, label name escaping.
util/testrecord	Test-only WAL record helpers.
util/teststorage	The default in-memory storage used by scrape_test.go, rules_test.go, etc.
util/testutil	Misc test helpers: temp dirs, lifecycle gates, signal injection.
util/testwal	Test WAL helpers.
util/treecache	Zookeeper tree cache used by the Zookeeper SD.
util/zeropool	Generic, typed sync.Pool (preferred over the standard library version on hot paths).

Highlights

util/features

The feature flag registry. util/features/features.go defines:

• Category constants: API, OTLPReceiver, Prometheus, PromQL, PromQLFunctions, PromQLOperators, Rules, Scrape, ServiceDiscoveryProviders, TemplatingFunctions, TSDB, UI.
• Collector interface — Enable, Disable, Set, Get.
• DefaultRegistry — the global default used by every subsystem.

Subsystems call features.Set(features.PromQL, "experimental_functions", enabled) during construction. The /api/v1/features endpoint serialises the registry for the UI.

util/pool

Size-class pool used everywhere a []byte is reused (scrape, remote write, WAL). Construction:

buffers := pool.New(1e3, 100e6, 3, func(sz int) any { return make([]byte, 0, sz) })
buf := buffers.Get(needed).([]byte)
defer buffers.Put(buf)

util/zeropool

Generic, typed wrapper over sync.Pool:

var samplesPool zeropool.Pool[[]sample]
s := samplesPool.Get()  // []sample
// use s
samplesPool.Put(s[:0])

Used heavily by promql/engine.go to avoid per-step allocations.

util/annotations

Annotations are typed warnings/infos that flow alongside Result:

warns := annotations.New().Add(
    annotations.NewMixedFloatsHistogramsWarning(matrixSelector, posrange),
)

Each New<Name> constructor returns a func(...) annotations.Annotation to make the call sites short and readable.

util/gate

A simple counting semaphore. The engine uses one to bound concurrent queries:

gate := gate.New(maxConcurrent)
gate.Start(ctx)        // blocks until a slot is free
defer gate.Done()

Entry points for modification

• Adding a primitive: create a new sub-package; keep dependencies minimal so any subsystem can import it.
• Adding to util/features: new categories should be rare; use existing ones (PromQL, Scrape) when possible.
• Adding an annotation: define the New<Name> constructor in util/annotations/annotations.go and emit it from the relevant evaluator branch.