otgrpc

README

OpenTracing support for gRPC in Go

The otgrpc package makes it easy to add OpenTracing support to gRPC-based systems in Go.

Installation

go get github.com/grpc-ecosystem/grpc-opentracing/go/otgrpc

Documentation

See the basic usage examples below and the package documentation on godoc.org.

Client-side usage example

Wherever you call grpc.Dial:

// You must have some sort of OpenTracing Tracer instance on hand.
var tracer opentracing.Tracer = ...
...

// Set up a connection to the server peer.
conn, err := grpc.Dial(
    address,
    ... // other options
    grpc.WithUnaryInterceptor(
        otgrpc.OpenTracingClientInterceptor(tracer)),
    grpc.WithStreamInterceptor(
        otgrpc.OpenTracingStreamClientInterceptor(tracer)))

// All future RPC activity involving `conn` will be automatically traced.

Server-side usage example

Wherever you call grpc.NewServer:

// You must have some sort of OpenTracing Tracer instance on hand.
var tracer opentracing.Tracer = ...
...

// Initialize the gRPC server.
s := grpc.NewServer(
    ... // other options
    grpc.UnaryInterceptor(
        otgrpc.OpenTracingServerInterceptor(tracer)),
    grpc.StreamInterceptor(
        otgrpc.OpenTracingStreamServerInterceptor(tracer)))

// All future RPC activity involving `s` will be automatically traced.

Documentation

Overview

Package otgrpc provides OpenTracing support for any gRPC client or server.

See the README for simple usage examples: https://github.com/grpc-ecosystem/grpc-opentracing/blob/master/go/otgrpc/README.md

Index

• Variables
• func FromContext(ctx context.Context) (md metadata.MD, ok bool)
• func New(m map[string]string) metadata.MD
• func NewContext(ctx context.Context, md metadata.MD) context.Context
• func OpenTracingClientInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.UnaryClientInterceptor
• func OpenTracingServerInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.UnaryServerInterceptor
• func OpenTracingStreamClientInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.StreamClientInterceptor
• func OpenTracingStreamServerInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.StreamServerInterceptor
• func SetSpanTags(span opentracing.Span, err error, client bool)
• type Class
  • func ErrorClass(err error) Class
• type Option
  • func IncludingSpans(inclusionFunc SpanInclusionFunc) Option
  • func LogError() Option
  • func LogPayloads() Option
  • func SpanDecorator(decorator SpanDecoratorFunc) Option
  • func WithServerInterceptor(serverInterceptor grpc.UnaryServerInterceptor) Option
  • func WithStreamServerInterceptor(streamServerInterceptor grpc.StreamServerInterceptor) Option
• type SpanDecoratorFunc
• type SpanInclusionFunc

Variables

var (

	// StartSpanFactory ...
	StartSpanFactory = defaultStartSpan
)

Functions

func FromContext

func FromContext(ctx context.Context) (md metadata.MD, ok bool)

FromContext returns the MD in ctx if it exists.

func New

func New(m map[string]string) metadata.MD

New creates a MD from given key-value map.

func NewContext

func NewContext(ctx context.Context, md metadata.MD) context.Context

NewContext creates a new context with md attached.

func OpenTracingClientInterceptor

func OpenTracingClientInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.UnaryClientInterceptor

OpenTracingClientInterceptor returns a grpc.UnaryClientInterceptor suitable for use in a grpc.Dial call.

For example:

conn, err := grpc.Dial(
    address,
    ...,  // (existing DialOptions)
    grpc.WithUnaryInterceptor(otgrpc.OpenTracingClientInterceptor(tracer)))

All gRPC client spans will inject the OpenTracing SpanContext into the gRPC metadata; they will also look in the context.Context for an active in-process parent Span and establish a ChildOf reference if such a parent Span could be found.

func OpenTracingServerInterceptor

func OpenTracingServerInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.UnaryServerInterceptor

OpenTracingServerInterceptor returns a grpc.UnaryServerInterceptor suitable for use in a grpc.NewServer call.

For example:

s := grpc.NewServer(
    ...,  // (existing ServerOptions)
    grpc.UnaryInterceptor(otgrpc.OpenTracingServerInterceptor(tracer)))

All gRPC server spans will look for an OpenTracing SpanContext in the gRPC metadata; if found, the server span will act as the ChildOf that RPC SpanContext.

Root or not, the server Span will be embedded in the context.Context for the application-specific gRPC handler(s) to access.

func OpenTracingStreamClientInterceptor

func OpenTracingStreamClientInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.StreamClientInterceptor

OpenTracingStreamClientInterceptor returns a grpc.StreamClientInterceptor suitable for use in a grpc.Dial call. The interceptor instruments streaming RPCs by creating a single span to correspond to the lifetime of the RPC's stream.

For example:

conn, err := grpc.Dial(
    address,
    ...,  // (existing DialOptions)
    grpc.WithStreamInterceptor(otgrpc.OpenTracingStreamClientInterceptor(tracer)))

All gRPC client spans will inject the OpenTracing SpanContext into the gRPC metadata; they will also look in the context.Context for an active in-process parent Span and establish a ChildOf reference if such a parent Span could be found.

func OpenTracingStreamServerInterceptor

func OpenTracingStreamServerInterceptor(tracer opentracing.Tracer, optFuncs ...Option) grpc.StreamServerInterceptor

OpenTracingStreamServerInterceptor returns a grpc.StreamServerInterceptor suitable for use in a grpc.NewServer call. The interceptor instruments streaming RPCs by creating a single span to correspond to the lifetime of the RPC's stream.

For example:

s := grpc.NewServer(
    ...,  // (existing ServerOptions)
    grpc.StreamInterceptor(otgrpc.OpenTracingStreamServerInterceptor(tracer)))

All gRPC server spans will look for an OpenTracing SpanContext in the gRPC metadata; if found, the server span will act as the ChildOf that RPC SpanContext.

Root or not, the server Span will be embedded in the context.Context for the application-specific gRPC handler(s) to access.

func SetSpanTags

func SetSpanTags(span opentracing.Span, err error, client bool)

SetSpanTags sets one or more tags on the given span according to the error.

Types

type Class

type Class string

A Class is a set of types of outcomes (including errors) that will often be handled in the same way.

const (
	Unknown Class = "0xx"
	// Success represents outcomes that achieved the desired results.
	Success Class = "2xx"
	// ClientError represents errors that were the client's fault.
	ClientError Class = "4xx"
	// ServerError represents errors that were the server's fault.
	ServerError Class = "5xx"
)

func ErrorClass

func ErrorClass(err error) Class

ErrorClass returns the class of the given error

type Option

type Option func(o *options)

Option instances may be used in OpenTracing(Server|Client)Interceptor initialization.

See this post about the "functional options" pattern: http://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis

func IncludingSpans

func IncludingSpans(inclusionFunc SpanInclusionFunc) Option

IncludingSpans binds a IncludeSpanFunc to the options

func LogError

func LogError() Option

LogError returns an Option that tells the OpenTracing instrumentation to try to log errors in both directions.

func LogPayloads

func LogPayloads() Option

LogPayloads returns an Option that tells the OpenTracing instrumentation to try to log application payloads in both directions.

func SpanDecorator

func SpanDecorator(decorator SpanDecoratorFunc) Option

SpanDecorator binds a function that decorates gRPC Spans.

func WithServerInterceptor

func WithServerInterceptor(serverInterceptor grpc.UnaryServerInterceptor) Option

WithServerInterceptor ...

func WithStreamServerInterceptor

func WithStreamServerInterceptor(streamServerInterceptor grpc.StreamServerInterceptor) Option

WithStreamServerInterceptor ...

type SpanDecoratorFunc

type SpanDecoratorFunc func(
	ctx context.Context,
	span opentracing.Span,
	method string,
	req, resp interface{},
	grpcError error)

SpanDecoratorFunc provides an (optional) mechanism for otgrpc users to add arbitrary tags/logs/etc to the opentracing.Span associated with client and/or server RPCs.

type SpanInclusionFunc

type SpanInclusionFunc func(
	parentSpanCtx opentracing.SpanContext,
	method string,
	req, resp interface{}) bool

SpanInclusionFunc provides an optional mechanism to decide whether or not to trace a given gRPC call. Return true to create a Span and initiate tracing, false to not create a Span and not trace.

parentSpanCtx may be nil if no parent could be extraction from either the Go context.Context (on the client) or the RPC (on the server).