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/opentracing-contrib/go-grpc

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.
Expand ▾ Collapse ▴

Documentation

Overview

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

    See the README for simple usage examples: https://github.com/opentracing-contrib/go-grpc/README.md

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    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 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.

                          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).

                              Directories

                              Path Synopsis
                              test
                              otgrpc_testing
                              Package otgrpc_testing is a generated protocol buffer package.
                              Package otgrpc_testing is a generated protocol buffer package.