client_golang

client_golang is the official Go client library for Prometheus, providing the core primitives (Counter, Gauge, Histogram, Summary) used to instrument application code, plus a registry for collecting and exposing those metrics. It also ships an HTTP client for querying the Prometheus HTTP API and a Pushgateway push client for batch jobs.

Maintained directly under the prometheus GitHub organization, it is the reference implementation most other language clients follow conceptually, and is the default choice for any Go service that needs to expose /metrics for Prometheus scraping.

What You Get

• Core metric types — Counter, Gauge, Histogram, Summary — plus their …Vec variants for labeled metrics
• A Registry/Registerer/Gatherer abstraction for collecting metrics from custom Collector implementations
• promhttp.Handler() to expose a standard /metrics endpoint in Prometheus text or OpenMetrics exposition format
• promauto constructors that register metrics automatically at construction time, removing boilerplate MustRegister calls
• Built-in collectors for Go runtime stats (goroutines, GC, memstats) and process stats (CPU, memory, file descriptors)
• A push package for sending metrics to a Prometheus Pushgateway from batch/cron jobs
• testutil helpers (CollectAndCompare, ToFloat64, GatherAndCompare) for asserting on metric values in unit tests

Common Use Cases

• Exposing a /metrics endpoint on a Go web service or API for Prometheus to scrape
• Instrumenting request counts, latencies, and error rates with labeled CounterVec/HistogramVec metrics
• Reporting custom application-level gauges (queue depth, active connections, cache hit ratio)
• Pushing metrics from short-lived batch jobs or cron tasks via the Pushgateway client
• Writing unit tests that assert specific metric values were recorded after an operation

Under The Hood

Architecture — The core of the library is prometheus/registry.go, which implements a Registry type satisfying both the Registerer interface (for registering Collectors) and the Gatherer interface (for scraping all registered collectors into a slice of dto.MetricFamily protobuf messages via internal goroutine-fed channels, capMetricChan/capDescChan). Individual metric types (counter.go, gauge.go, histogram.go — the latter alone is over 2,000 lines, covering both classic fixed-bucket histograms and native/sparse exponential histograms) implement the Metric and Collector interfaces so they can be registered directly or embedded inside custom collectors. promhttp/http.go wraps a Gatherer in an http.Handler that negotiates between Prometheus text format and OpenMetrics via content negotiation, applying gzip and error-handling options. promauto/auto.go is a thin factory layer over the same constructors that registers on creation and panics on failure, trading explicitness for reduced boilerplate. Sub-packages (collectors, push, testutil, api/prometheus) are independently importable so consumers only pull in what they use.

Tech Stack — Pure Go (99.3% of the codebase per GitHub’s language breakdown), targeting the two most recent major Go releases per its documented support policy (currently requiring Go 1.25 per go.mod). Dependencies are minimal and deliberately scoped: github.com/prometheus/client_model and google.golang.org/protobuf for the wire format, github.com/prometheus/common for shared exposition-format helpers, github.com/cespare/xxhash/v2 for fast label hashing, github.com/beorn7/perks for streaming quantile estimation in Summaries, and github.com/klauspost/compress for response compression in promhttp. No code generation frameworks or external build tooling beyond a standard Makefile.

Code Quality — Extensive test coverage: 69 _test.go files against 162 total .go files (roughly 43% of files are tests), including dedicated example tests (example_*_test.go) that double as executable documentation, a lint.go/promlint sub-package that validates metric naming conventions, and testutil.go exposing CollectAndCompare/GatherAndCompare specifically so downstream consumers can unit-test their own instrumentation. The .golangci.yml config enforces a strict lint baseline across the module. Error handling is explicit throughout — registration failures return errors (or panic only in the promauto/Must* variants, which is a documented, opt-in tradeoff) rather than failing silently.

API Design — The public API is built around small, composable interfaces (Collector, Registerer, Gatherer, Metric) which is idiomatic Go but does require understanding the collector/registry split before writing anything nontrivial — this is the library’s main source of onboarding friction. promauto exists specifically to shortcut that with import-and-call constructors for the common case. Naming is highly consistent (NewCounter/NewCounterVec/NewGauge/NewGaugeVec follow one predictable pattern), and the package-level doc.go includes a complete runnable example. The separation of instrumentation (prometheus), exposition (promhttp), auto-registration (promauto), and testing (testutil) into distinct importable sub-packages keeps each consumer’s dependency footprint minimal.