Util

pkg/util/ is the catch-all for foundation packages — the things the rest of CockroachDB imports without thinking about. There are roughly 115 sub-packages here. This page is a tour of the ones you are likely to touch.

High-traffic foundations

Sub-package	What it does
pkg/util/log/	Structured, redactable, multi-sink logger. Channels, file rotation, OTLP, fluent.
pkg/util/tracing/	OpenTelemetry-based tracing. Span verbose-event helpers, recording, propagation.
pkg/util/metric/	Prometheus-compatible metrics primitives. Owns counter/gauge/histogram.
pkg/util/hlc/	Hybrid Logical Clock. The cluster's time primitive.
pkg/util/syncutil/	Mutex, RWMutex with deadlock detection in race builds; IntMap, singleflight.
pkg/util/ctxgroup/	errgroup-style group with context cancellation.
pkg/util/stop/	Stopper — owns goroutine lifecycles. Used everywhere.
pkg/util/retry/	Retry-with-backoff helper.
pkg/util/quotapool/	Generic resource quota pool.
pkg/util/randutil/	Seeded RNG used by tests.
pkg/util/timeutil/	Time helpers; time.Now() substitute.
pkg/util/uuid/	UUID v4/v5 helpers.
pkg/util/encoding/	The CRDB key encoding (used by MVCC, indexes).
pkg/util/protoutil/	Marshal/Unmarshal helpers; proto cloning.
pkg/util/leaktest/	Goroutine leak detection in tests.
pkg/util/envutil/	Centralized os.Getenv registry.
pkg/util/admission/	Cluster-wide admission control engine.
pkg/util/circuit/	Async circuit breakers.
pkg/util/optional/	Generic Optional[T].

Domain types

Sub-package	Type
pkg/util/duration/	Duration (months/days/nanos) — Postgres INTERVAL
pkg/util/timeofday/	TimeOfDay
pkg/util/timetz/	TimeTZ
pkg/util/ipaddr/	IPAddr (IPv4/IPv6)
pkg/util/json/	JSONB type and operations
pkg/util/jsonpath/	JSONPath expression evaluator
pkg/util/bitarray/	Bit array (BIT)
pkg/util/uint128/	128-bit unsigned arithmetic
pkg/util/vector/	Vector type (used by VECTOR / vecindex)
pkg/util/ulid/	ULIDs
pkg/util/ltree/	Ltree type
pkg/util/trigram/	Trigram extraction for pg_trgm
pkg/util/tsearch/	Text search vectors and queries

Collections

Sub-package	Type
pkg/util/cache/	LRU and unordered caches
pkg/util/interval/	Interval tree
pkg/util/intsets/	Compact int set
pkg/util/ring/	Ring buffer
pkg/util/queue/	Generic FIFO queue
pkg/util/container/	Generic containers

I/O and OS

Sub-package	What it does
pkg/util/sysutil/	System calls (rlimit, kernel info)
pkg/util/cgroups/	cgroup-aware resource limits
pkg/util/grpcutil/	gRPC-specific helpers
pkg/util/httputil/	HTTP client helpers
pkg/util/netutil/	Listeners, peer detection
pkg/util/sdnotify/	systemd READY notifications
pkg/util/fileutil/	File path helpers
pkg/util/pprofutil/	pprof helpers

Test infrastructure

Sub-package	What it does
pkg/util/leaktest/	Goroutine leak detection
pkg/util/metamorphic/	Metamorphic test framework
pkg/util/randident/	Random identifier generator
pkg/util/buildutil/	Build-tag awareness
pkg/util/system/	Conservative runtime.NumCPU
pkg/util/grunning/	Per-goroutine running time

Performance and scheduling

Sub-package	What it does
pkg/util/admission/	Admission control (cpu, store IO, networking)
pkg/util/goschedstats/	Scheduler latency observation
pkg/util/schedulerlatency/	Periodic scheduler-latency probe
pkg/util/taskpacer/	Pace work to keep CPU/IO healthy
pkg/util/taskset/	Bind goroutines to CPU sets
pkg/util/limit/	Concurrency limiters
pkg/util/slidingwindow/	Sliding-window aggregator

Why so many?

The repo's policy is to build foundations as separate, narrowly-scoped packages so that internal subsystems can import only what they need. This avoids a "kitchen sink" util import that would force every consumer to pay for unrelated dependencies.

When you build a new helper, ask: does it belong next to the consumer (e.g. inside pkg/sql/...util/), or is it cluster-wide? Cluster-wide foundation work goes into a new pkg/util/<name>/ sub-package with its own BUILD.bazel and tests.

Related pages

• Many pages link directly into pkg/util/... — for example pkg/util/hlc/ is referenced by systems/storage, systems/kv, systems/raft, and the glossary.