transport-metrics¶

Cardinality-safe Prometheus instrumentation for Go services.

One Register call mounts a Prometheus /metrics endpoint on your mux, already carrying the Go runtime, process and build-info collectors. Nothing else has to be running: watch heap, goroutines, GC and uptime, and add WithPprof to chase a leak with go tool pprof.

mux := http.NewServeMux()
// mount your API handlers…
_ = metrics.Register(mux, metrics.WithMiddleware(authMiddleware))

Prometheus, complementing OTel¶

This is the pull/scrape (Prometheus) counterpart to the push (OTel) go/observability modules, and complements them rather than replacing them. Use Prometheus for local, single-binary tools and classic scrape stacks, OTel when you have an OTLP pipeline, and both if you like. See Pull vs push.

Highlights¶

• Zero infra. Scrape or curl /metrics locally. No collector required.
• Runtime out of the box. Go + process + build_info collectors on a private registry by default.
• Guarded posture. Pass your auth middleware, or bind to loopback, so the port is never open. Mounting unguarded logs a warning.
• Lean core, opt-in weight. The core links only prometheus/client_golang, go/errors and the standard library; go/transport (standalone server), gRPC and OTel live in opt-in subpackages.

What this does not do¶

No push: no OTLP exporter, no remote write, no Pushgateway. No configuration file, environment variables or flags; it is configured in Go. No instrumentation of outbound HTTP or gRPC calls. The full inventory, marked deliberate or not-yet-built, is What transport-metrics does not do.

Where next¶

• Tutorials: getting started for a running /metrics endpoint · catch a memory leak with the endpoint and pprof together.
• How-to: guard the endpoint, custom collectors, standalone server, pprof, HTTP requests, gRPC servers, exemplars, business logic, resources.
• Reference: options · every metric · failure modes · pkg.go.dev.
• Explanation: pull vs push, cardinality safety, limitations, architecture & roadmap.

Part of the phpboyscout Go toolkit.

Further reading¶

The blog carries a curated route through this subject: Building a web service in Go collects everything written about it, ordered so you can start at the beginning rather than newest-first.