go-grpc-middleware: Open Source Monitoring & Observability

What is go-grpc-middleware?

go-grpc-middleware is an Apache-2.0 Go library published by the grpc-ecosystem that provides ready-to-use gRPC interceptors — reusable middleware for authentication, logging, retries, metrics and panic recovery — for developers building Go microservices on gRPC.

What it is

The repository holds gRPC Go middlewares: interceptors, helpers and utilities. gRPC Go supports interceptors, which are functions that execute on the server before a request reaches application logic, or on the client around the user's call. This project packages those interceptors as importable code, published under the module path github.com/grpc-ecosystem/go-grpc-middleware/v2, so a service can attach shared behaviour to every RPC method instead of rewriting it per handler. It lives in the grpc-ecosystem organisation next to grpc-go, which it extends rather than replaces.

The concrete problem it solves is duplicated cross-cutting code. Without it, teams hand-write the same authentication check, request logger, metric recording and panic recovery logic in every service and every method. This library replaces that per-service boilerplate with explicitly chained interceptors, and it deliberately skips interceptors that dedicated projects already maintain well, linking to them instead in its interceptors list. The README describes the outcome as semi-automatic instrumentation that improves the consistency of observability signals and enables correlation techniques such as exemplars and trace IDs written into logs.

Key capabilities

Chains interceptors explicitly through grpc.ChainUnaryInterceptor and grpc.ChainStreamInterceptor, so shared functionality applies to all gRPC methods in a defined order.
Provides an auth interceptor at github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth, customisable through an AuthFunc.
Provides logging interceptors, logging.UnaryServerInterceptor and logging.StreamServerInterceptor, with options such as logging.WithFieldsFromContext(logTraceID).
Provides recovery interceptors, recovery.UnaryServerInterceptor and recovery.StreamServerInterceptor, configured with recovery.WithRecoveryHandler(grpcPanicRecoveryHandler).
Provides a selector interceptor, selector.UnaryServerInterceptor, which scopes another interceptor to matching methods through selector.MatchFunc(allButHealthZ).
Integrates with metrics and tracing middleware using grpcprom.WithExemplarFromContext, grpcprom.WithLabelsFromContext and grpc.StatsHandler(otelgrpc.NewServerHandler()).
Ships buildable examples in the examples directory and tested interceptor usage in examples_test.go.

Who uses it and how

Go teams running several gRPC microservices that need the same authentication, logging and recovery behaviour applied uniformly rather than reimplemented per service.
Platform and infrastructure engineers wiring observability so that trace IDs appear in logs and metrics carry exemplars, combining the logging and grpcprom interceptors in one chain.
Services that must exempt certain endpoints from authentication or other middleware, handled by the selector interceptor with match functions such as allButHealthZ.
Developers who adopt the repository as a template and copy simpler interceptors when they need more flexibility than the shipped options allow.

Getting started

Install with go get github.com/grpc-ecosystem/go-grpc-middleware/v2, then follow the runnable server and client code in the examples directory. The README states that all interceptor paths work with go get.

How it compares

Among the tools the project's own documentation names, grpc-go supplies the underlying interceptor mechanism and this library builds ready-made middleware on top of it, while grpcprom and otelgrpc provide the metrics and OpenTelemetry instrumentation that its example chains compose. Where a dedicated project already covers a concern well, such as google.golang.org/grpc/authz for authorisation, the README links to that project rather than duplicating it, so this repository positions itself as the common cases and the glue between them, not as the only source of interceptors.

When to use it — and when not to

This is a library rather than a deployed product, so a self-hoster still operates the gRPC services plus the logging, metrics and tracing backends those interceptors feed. The README itself warns that the repository cannot support all edge cases and suggests copying simpler interceptors when more flexibility is needed, so teams needing firm policy guarantees or unusual interceptor behaviour should expect to maintain their own code. The project also carries 83 open issues, worth reviewing before adopting it as a standard.

project readme (upstream, from github) — read inline

Go gRPC Middleware

This repository holds gRPC Go Middlewares: interceptors, helpers and utilities.

Middleware

gRPC Go has support for "interceptors", i.e. middleware that is executed either on the gRPC Server before the request is passed onto the user's application logic, or on the gRPC client either around the user call. It is a perfect way to implement common patterns: auth, logging, tracing, metrics, validation, retries, rate limiting and more, which can be a great generic building blocks that make it easy to build multiple microservices easily.

Especially for observability signals (logging, tracing, metrics) interceptors offers semi-auto-instrumentation that improves consistency of your observability and allows great correlation techniques (e.g. exemplars and trace ID in logs). Demo-ed in examples.

This repository offers ready-to-use middlewares that implements gRPC interceptors with examples. In some cases dedicated projects offer great interceptors, so this repository skips those, and we link them in the interceptors list.

NOTE: Some middlewares are quite simple to write, so feel free to use this repo as template if you need. It's ok to copy some simpler interceptors if you need more flexibility. This repo can't support all the edge cases you might have.

Additional great feature of interceptors is the fact we can chain those. For example below you can find example server side chain of interceptors with full observabiliy correlation, auth and panic recovery:

	grpcSrv := grpc.NewServer(
		grpc.StatsHandler(otelgrpc.NewServerHandler()),
		grpc.ChainUnaryInterceptor(
			srvMetrics.UnaryServerInterceptor(
				grpcprom.WithExemplarFromContext(exemplarFromContext),
				grpcprom.WithLabelsFromContext(labelsFromContext),
			),
			logging.UnaryServerInterceptor(interceptorLogger(rpcLogger), logging.WithFieldsFromContext(logTraceID)),
			selector.UnaryServerInterceptor(auth.UnaryServerInterceptor(authFn), selector.MatchFunc(allButHealthZ)),
			recovery.UnaryServerInterceptor(recovery.WithRecoveryHandler(grpcPanicRecoveryHandler)),
		),
		grpc.ChainStreamInterceptor(
			srvMetrics.StreamServerInterceptor(
				grpcprom.WithExemplarFromContext(exemplarFromContext),
				grpcprom.WithLabelsFromContext(labelsFromContext),
			),
			logging.StreamServerInterceptor(interceptorLogger(rpcLogger), logging.WithFieldsFromContext(logTraceID)),
			selector.StreamServerInterceptor(auth.StreamServerInterceptor(authFn), selector.MatchFunc(allButHealthZ)),
			recovery.StreamServerInterceptor(recovery.WithRecoveryHandler(grpcPanicRecoveryHandler)),
		),
	)

This pattern offers clean and explicit shared functionality for all your gRPC methods. Full, buildable examples can be found in examples directory.

Interceptors

This list covers known interceptors that users use for their Go microservices (both in this repo and external). Click on each to see extended examples in examples_test.go (also available in pkg.go.dev)

All paths should work with go get .

Auth

github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/auth - a customizable via AuthFunc piece of auth middleware.
(external) google.golang.org/grpc/authz - more complex, customizable via auth polices (RBAC like), piece of auth middleware.

Observability

Metrics:
- github.com/grpc-ecosystem/go-grpc-middleware/providers/prometheus⚡ - Prometheus client-side and server-side monitoring middleware. Supports exemplars. Moved from deprecated now go-grpc-prometheus.
- (external) go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc - official OpenTelemetry interceptors (metric and tracing).
Logging with github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/logging - a customizable logging middleware offering extended per request logging. It requires logging adapter, see examples in interceptors/logging/examples for go-kit, log, logr, logrus, slog, zap and zerolog.
- NOTE: Interceptors with context field injections need to be chained before the adapter function.
Tracing:
- (external) go.opentelemetry.io/contrib/instrumentation/google.golang.org/grpc/otelgrpc - official OpenTelemetry interceptors (metric and tracing) as used in example.
- (external) github.com/grpc-ecosystem/go-grpc-middleware/tracing/opentracing - deprecated OpenTracing client-side and server-side interceptors if you still need it!

Client

github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/retry - a generic gRPC response code retry mechanism, client-side middleware.
- NOTE: grpc-go has native retries too with advanced policies (https://github.com/grpc/grpc-go/blob/v1.54.0/examples/features/retry/client/main.go)
github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/timeout - a generic gRPC request timeout, client-side middleware.

Server

github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/validator - codegen inbound message validation from .proto options.
github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/recovery - turn panics into gRPC errors (make sure to use those as "last" interceptor, so panic does not skip other interceptors).
github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/ratelimit - grpc rate limiting by your own limiter.
github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/protovalidate - message validation from .proto options via protovalidate-go

Filtering Interceptor

github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/selector - allow users to select given one or more interceptors in certain condition like matching service method.

Prerequisites

Go: Any one of the three latest major releases are supported.

Structure of this repository

The main interceptors are available in the subdirectories of the interceptors directory e.g. interceptors/validator, interceptors/auth or interceptors/logging.

Some interceptors or utilities of interceptors requires opinionated code that depends on larger amount of dependencies. Those are places in providers directory as separate Go module, with separate versioning. For example providers/prometheus offer metrics middleware (there is no "interceptor/metrics" at the moment). The separate module, might be a little bit harder to discover and version in your go.mod, but it allows core interceptors to be ultra slim in terms of dependencies.

The interceptors directory also holds generic interceptors that accepts Reporter interface which allows creating your own middlewares with ease.

As you might notice this repository contains multiple modules with different versions (Go Module specifics). Refer to versions.yaml for current modules. We have main module of version 2.x.y and providers mo

Frequently asked questions

Is go-grpc-middleware free to use?

go-grpc-middleware is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does go-grpc-middleware do?

Golang gRPC Middlewares: interceptor chaining, auth, logging, retries and more.

What is go-grpc-middleware written in?

go-grpc-middleware is primarily written in Go. Its source is publicly available at https://github.com/grpc-ecosystem/go-grpc-middleware, and it has 6,761 GitHub stars.