go-grpc-prometheus

go-grpc-prometheus provides ready-made gRPC interceptors that export Prometheus metrics for both unary and streaming RPCs, on the client and server side. Instead of hand-writing counters around every handler, you register the interceptor once and get request counts, per-message counts, and completion status broken down by gRPC service, method, and status code.

Latency histograms are opt-in (via EnableHandlingTimeHistogram / EnableClientHandlingTimeHistogram) since high-cardinality histograms are expensive for Prometheus to store and query. The project is now archived — its functionality has moved into go-grpc-middleware’s providers/prometheus package — but the v1.2.0 API documented here remains in wide use in existing gRPC codebases and is a useful reference for the metric-naming conventions it established.

What You Get

• Server-side and client-side interceptors for both unary and streaming gRPC calls
• Started/handled/message-sent/message-received counters labeled by grpc_type, grpc_service, grpc_method, and grpc_code
• Optional handling-time histograms for server and client RPCs, and per-message send/receive timers for streams
• A Register/InitializeMetrics helper that pre-populates all counters to zero for every registered service method, avoiding missing-metric gaps in dashboards
• Custom ClientMetrics/ServerMetrics instances (via NewClientMetrics/NewServerMetrics) for use with a non-default Prometheus registry, alongside ready-to-use Default*Metrics package-level instances

Common Use Cases

• Exposing standard RPC-rate, error-rate, and latency dashboards for a gRPC microservice fleet
• Alerting on unary request error percentage per service using the documented PromQL patterns
• Auditing gRPC service health during incident response by service/method/status-code breakdown
• Bootstrapping observability for a new gRPC service without writing custom instrumentation code

Under The Hood

Architecture The library splits cleanly into a metrics-holder layer and an interceptor layer: ServerMetrics/ClientMetrics (server_metrics.go, client_metrics.go) own the Prometheus counter/histogram vectors and implement prometheus.Collector directly, while server_reporter.go/client_reporter.go provide a small *Reporter type that each interceptor instantiates per-call to record started/received/sent/handled events against those vectors. server.go/client.go expose the package-level Default*Metrics singletons and convenience functions (Register, EnableHandlingTimeHistogram) built on top of the per-instance API, so the same code paths serve both the zero-config default registry and custom-registry setups. Streaming calls are handled via a monitoredServerStream wrapper around grpc.ServerStream that intercepts SendMsg/RecvMsg to increment message counters without altering call semantics. Changing the core grpcType/method-name extraction in util.go would ripple through every counter label across both client and server paths, since all reporters funnel through it.

Tech Stack Written in Go, targeting Go 1.9+, with google.golang.org/grpc for interceptor hooks and github.com/prometheus/client_golang for metric types, registries, and HTTP exposition helpers. Test dependencies include stretchr/testify (assert/require/suite) and prometheus/client_golang/prometheus/testutil for asserting exact metric output. CI runs via Travis (.travis.yml); there is no separate build system beyond the standard Go toolchain and a small makefile.

Code Quality Both server and client paths have dedicated test suites (server_test.go, client_test.go) built on testify/suite, spinning up a real in-process gRPC server/client pair against a generated test-proto service and asserting exact counter/histogram values via testutil. Error handling favors explicit status-code extraction (grpcstatus.FromError) over swallowing errors, and exported types carry conventional Go doc comments. There’s no dedicated linter config checked in, but naming is consistent throughout and the public API surface is intentionally small.

API Design The package favors near-zero-boilerplate defaults — package-level UnaryServerInterceptor/StreamServerInterceptor variables and a Register(server) call cover the common case, while NewServerMetrics/NewClientMetrics plus functional options (WithConstLabels, WithHistogramBuckets) support advanced custom-registry setups. Latency histograms are deliberately opt-in via explicit Enable*Histogram calls rather than on-by-default, reflecting an ergonomic, cost-aware choice rather than a novel technical approach — the overall design follows well-established Prometheus instrumentation-library conventions rather than introducing new ones, which is consistent with its role having since been absorbed into go-grpc-middleware.