pkg

Generic utilities shared across modules. Source: pkg/.

Purpose

go.etcd.io/etcd/pkg/v3 collects small, reusable helpers that don't belong in either the public API or the server. Rule of thumb: if the same helper is wanted by two of client/v3, server/, and tests/, it lives in pkg/.

Subpackages

Path	What it provides
pkg/adt/	Augmented data structures (interval tree, used by lease)
pkg/cobrautl/	Shared CLI bits — error printing, exit codes, version block — used by etcdctl and etcdutl
pkg/contention/	Detector for time-progress stalls; used to warn on Raft heartbeat lag
pkg/cpuutil/	Endianness detection, CPU info
pkg/crc/	CRC table for WAL records
pkg/debugutil/	pprof handler registration helper
pkg/expect/	Wraps os/exec to feed stdin/stdout for the e2e tests
pkg/featuregate/	Feature-gate registry (Kubernetes-style) — backs --feature-gates=
pkg/flags/	Custom flag.Value implementations (URLs, durations, boolish strings)
pkg/grpctesting/	gRPC test scaffolding
pkg/httputil/	http.Server.Shutdown helpers
pkg/idutil/	Monotonic ID generator
pkg/ioutil/	Read/Write helpers, PageWriter, LimitedBufferReader
pkg/netutil/	URL comparison, host resolution
pkg/notify/	Single-use closeable channel notifier
pkg/osutil/	Signal handlers, interrupt registration
pkg/pbutil/	Protobuf must-marshal helpers
pkg/proxy/	In-process L7 proxy used in tests for fault injection
pkg/report/	Latency/throughput stat collector for tools/benchmark
pkg/runtime/	FD-count metrics
pkg/schedule/	FIFO scheduler used by MVCC compaction
pkg/stringutil/	Random ID/string generation for tests
pkg/traceutil/	Per-request trace recorder (the source of "took too long" logs)
pkg/wait/	Wait map: register an ID, get a chan back, fulfill from another goroutine

Key abstractions

Symbol	File	Why it matters
featuregate.MutableFeatureGate	pkg/featuregate/feature_gate.go	The struct returned by --feature-gates; server-wide gate state
traceutil.TraceFromContext / (*Trace).Step	pkg/traceutil/trace.go	Inserts the per-request trace that the server logs above 100 ms
wait.New() returning wait.Wait	pkg/wait/wait.go	Used by EtcdServer to pair Raft proposals with their responses
schedule.NewFIFOScheduler	pkg/schedule/schedule.go	Backs MVCC's background compaction
flags.URLsValue	pkg/flags/urls.go	Parses comma-separated URL flags like --listen-peer-urls
idutil.NewGenerator	pkg/idutil/id.go	Generates request IDs that survive restarts and avoid collision

How it is consumed

• server/: nearly every subpackage uses traceutil, wait, featuregate, idutil, schedule, and the flag value types.
• client/v3: uses cobrautl (via etcdctl), flags (via etcdctl), pbutil, traceutil for client-side tracing.
• tests/e2e: uses expect and proxy to drive child processes and inject faults.
• tools/benchmark: uses report for histograms.

Stability

pkg/ is technically a public Go module (it has its own go.mod), but the maintainers do not commit to API stability for it. Don't import pkg/v3/... from non-etcd code unless you're prepared for breakage.

Entry points for modification

If you need a brand-new helper, ask: should it live in:

• pkg/ (generic, used by 2+ etcd modules) — yes,
• client/pkg/ (only client-side concerns like TLS or file IO) — different module,
• the consumer module's internal/ — preferred when only one module needs it.