grpcmetrics

README

Go OpenTelemtry gRPC Metrics Instrumention

It is an OpenTelemetry (OTel) metric instrumentation for Golang gRPC servers and clients based on gRPC Stats.

Install

$ go get github.com/mahboubii/grpcmetrics

Usage

Metrics are reported based on General RFC conventions specefications with some exceptions for following metrics where a normal counter is used instead of histograms to reduce the metrics cardinality:

1. rpc.server.requests_per_rpc
2. rpc.server.responses_per_rpc
3. rpc.client.requests_per_rpc
4. rpc.client.responses_per_rpc

Keep in mind durations, request.size and response.size are not reported by default. If you need to enable them check out the options.

Server side metrics

handler, err := grpcmetrics.NewServerHandler()
if err != nil {
    log.Panic(err)
}

server := grpc.NewServer(
    grpc.StatsHandler(handler),

    // disable default otelgrpc duration metric to avoid sending metrics twice:
    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
        otelgrpc.UnaryServerInterceptor(otelgrpc.WithMeterProvider(otelmetric.NewNoopMeterProvider())),
    )),
    grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(
        otelgrpc.StreamServerInterceptor(otelgrpc.WithMeterProvider(otelmetric.NewNoopMeterProvider())),
    )),
)

Client side metrics

handler, err := grpcmetrics.NewClientHandler()
if err != nil {
    log.Panic(err)
}

connection, err := grpc.Dial("server:8080", grpc.WithStatsHandler(handler))

Documentation

Index

• Constants
• func NewClientHandler(options ...Option) (stats.Handler, error)
• func NewServerHandler(options ...Option) (stats.Handler, error)
• type Handler
  • func (h *Handler) HandleConn(_ context.Context, _ stats.ConnStats)
  • func (h *Handler) HandleRPC(ctx context.Context, rs stats.RPCStats)
  • func (h *Handler) TagConn(ctx context.Context, _ *stats.ConnTagInfo) context.Context
  • func (h *Handler) TagRPC(ctx context.Context, info *stats.RPCTagInfo) context.Context
• type Option
  • func WithInstrumentLatency(instrumentLatency bool) Option
  • func WithInstrumentSizes(instrumentSizes bool) Option
  • func WithInstrumentationName(name string) Option
  • func WithMeterProvider(p metric.MeterProvider) Option

Constants

const (
	// DefaultInstrumentationName is the default used when creating meters.
	DefaultInstrumentationName = "github.com/mahboubii/grpcmetrics"
)

Functions

func NewClientHandler

func NewClientHandler(options ...Option) (stats.Handler, error)

func NewServerHandler

func NewServerHandler(options ...Option) (stats.Handler, error)

Types

type Handler

type Handler struct {
	// contains filtered or unexported fields
}

Handler implements https://pkg.go.dev/google.golang.org/grpc/stats#Handler

func (*Handler) HandleConn

func (h *Handler) HandleConn(_ context.Context, _ stats.ConnStats)

HandleConn exists to satisfy gRPC stats.Handler interface.

func (*Handler) HandleRPC

func (h *Handler) HandleRPC(ctx context.Context, rs stats.RPCStats)

HandleRPC implements per-RPC stats instrumentation.

func (*Handler) TagConn

func (h *Handler) TagConn(ctx context.Context, _ *stats.ConnTagInfo) context.Context

TagConn exists to satisfy gRPC stats.Handler interface.

func (*Handler) TagRPC

func (h *Handler) TagRPC(ctx context.Context, info *stats.RPCTagInfo) context.Context

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option applies an option value when creating a Handler.

func WithInstrumentLatency

func WithInstrumentLatency(instrumentLatency bool) Option

WithInstrumentLatency enable instrument for rpc.{server|client}.duration. This is a histogram which is quite costly.

func WithInstrumentSizes

func WithInstrumentSizes(instrumentSizes bool) Option

WithInstrumentSizes enable instrument for rpc.{server|client}.response.size and rpc.{server|client}.request.size. This is a histogram which is quite costly.

func WithInstrumentationName

func WithInstrumentationName(name string) Option

WithInstrumentationName returns an Option to set custom name for metrics scope.

func WithMeterProvider

func WithMeterProvider(p metric.MeterProvider) Option

WithMeterProvider returns an Option to use custom MetricProvider when creating metrics.