otgrpc

README

Go gRPC Opentracing Instrumentation

An attempt to use Opentracing with gRPC services. The official grpc-opentracing library currently only supports tracing unary calls. This library makes use of gRPC stats.Handler interface to add tracing to gRPC streams as well.

The obvious approach to add tracing would be to make use of gRPC interceptors. However, the current interceptor interfaces lack the fuctionality to effectively add tracing information to the calls. Go gRPC has a built-in tracing mechanism that hooks into x/net/trace, but, the captured data is not accessible from external code. This leads us to the stats.Handler interface which is primarily designed for stats gathering but, in the process, gives us access to all interesting events that happen during a RPC -- which can be used to gather the tracing information we need.

Usage

Grab the library:

go get github.com/charithe/otgrpc

Client side:

tracer := // Tracer implementation

th := otgrpc.NewTraceHandler(tracer)
conn, err := grpc.Dial(address, grpc.WithStatsHandler(th))
...

Server side:

tracer := // Tracer implementation

th := otgrpc.NewTraceHandler(tracer)
server := grpc.NewServer(grpc.StatsHandler(th))
...

Options

Limit tracing to methods of your choosing

tf := func(method string) bool {
    return method == "/my.svc/my.method"
}

th := otgrpc.NewTraceHandler(tracer, orgrpc.WithTraceEnabledFunc(tf))

Attach payloads as Span log events

th := otgrpc.NewTraceHandler(tracer, otgrpc.WithPayloadLogging())

Documentation

Index

• Constants
• Variables
• type MetadataReaderWriter
  • func NewMetadataReaderWriter(md metadata.MD) *MetadataReaderWriter
  • func (mrw *MetadataReaderWriter) ForeachKey(handler func(string, string) error) error
  • func (mrw *MetadataReaderWriter) Set(key, value string)
• type Option
  • func WithPayloadLogging() Option
  • func WithTraceEnabledFunc(f func(method string) bool) Option
• type TraceHandler
  • func NewTraceHandler(tracer opentracing.Tracer, o ...Option) *TraceHandler
  • func (th *TraceHandler) HandleConn(ctx context.Context, s stats.ConnStats)
  • func (th *TraceHandler) HandleRPC(ctx context.Context, s stats.RPCStats)
  • func (th *TraceHandler) TagConn(ctx context.Context, tagInfo *stats.ConnTagInfo) context.Context
  • func (th *TraceHandler) TagRPC(ctx context.Context, tagInfo *stats.RPCTagInfo) context.Context

Constants

const (
	EventKey   = "event"
	PayloadKey = "payload"
)

Variables

var GRPCComponentTag = opentracing.Tag{Key: string(ext.Component), Value: "gRPC"}

Types

type MetadataReaderWriter

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

func NewMetadataReaderWriter

func NewMetadataReaderWriter(md metadata.MD) *MetadataReaderWriter

NewMetadataReaderWriter creates an object that implements the opentracing.TextMapReader and opentracing.TextMapWriter interfaces

func (*MetadataReaderWriter) ForeachKey

func (mrw *MetadataReaderWriter) ForeachKey(handler func(string, string) error) error

func (*MetadataReaderWriter) Set

func (mrw *MetadataReaderWriter) Set(key, value string)

type Option

type Option func(*options)

func WithPayloadLogging

func WithPayloadLogging() Option

WithPayloadLogging enables logging of RPC payloads

func WithTraceEnabledFunc

func WithTraceEnabledFunc(f func(method string) bool) Option

WithTraceEnabledFunc defines a function that indicates to the tracing implementation whether the method should be traced or not

type TraceHandler

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

func NewTraceHandler

func NewTraceHandler(tracer opentracing.Tracer, o ...Option) *TraceHandler

NewTraceHandler creates a gRPC stats.Handler instance that instruments RPCs with Opentracing trace contexts

func (*TraceHandler) HandleConn

func (th *TraceHandler) HandleConn(ctx context.Context, s stats.ConnStats)

func (*TraceHandler) HandleRPC

func (th *TraceHandler) HandleRPC(ctx context.Context, s stats.RPCStats)

func (*TraceHandler) TagConn

func (th *TraceHandler) TagConn(ctx context.Context, tagInfo *stats.ConnTagInfo) context.Context

func (*TraceHandler) TagRPC

func (th *TraceHandler) TagRPC(ctx context.Context, tagInfo *stats.RPCTagInfo) context.Context