grpc

Documentation

Overview

Package grpc provides functions to trace the google.golang.org/grpc package v1.2.

Example (Client)

package main

import (
	"log"

	grpctrace "github.com/DataDog/dd-trace-go/v2/contrib/google.golang.org/grpc"

	"google.golang.org/grpc"
)

func main() {
	// Create the client interceptor using the grpc trace package.
	si := grpctrace.StreamClientInterceptor(grpctrace.WithService("my-grpc-client"))
	ui := grpctrace.UnaryClientInterceptor(grpctrace.WithService("my-grpc-client"))

	// Dial in using the created interceptor.
	// Note: To use multiple UnaryInterceptors with grpc.Dial, you must use
	// grpc.WithChainUnaryInterceptor instead (as of google.golang.org/grpc v1.51.0).
	conn, err := grpc.Dial("localhost:50051", grpc.WithInsecure(),
		grpc.WithStreamInterceptor(si), grpc.WithUnaryInterceptor(ui))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()

	// And continue using the connection as normal.
}

Example (Server)

package main

import (
	"log"
	"net"

	grpctrace "github.com/DataDog/dd-trace-go/v2/contrib/google.golang.org/grpc"

	"google.golang.org/grpc"
)

func main() {
	// Create a listener for the server.
	ln, err := net.Listen("tcp", ":50051")
	if err != nil {
		log.Fatal(err)
	}

	// Create the server interceptor using the grpc trace package.
	si := grpctrace.StreamServerInterceptor(grpctrace.WithService("my-grpc-server"))
	ui := grpctrace.UnaryServerInterceptor(grpctrace.WithService("my-grpc-server"))

	// Initialize the grpc server as normal, using the tracing interceptor.
	s := grpc.NewServer(grpc.StreamInterceptor(si), grpc.UnaryInterceptor(ui))

	// ... register your services

	// Start serving incoming connections.
	if err := s.Serve(ln); err != nil {
		log.Fatalf("failed to serve: %v", err)
	}
}

Index

• Constants
• Variables
• func NewClientStatsHandler(opts ...Option) stats.Handler
• func NewServerStatsHandler(opts ...Option) stats.Handler
• func RegisterFixtureServer(s grpc.ServiceRegistrar, srv FixtureServer)
• func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor
• func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor
• type FixtureClient
  • func NewFixtureClient(cc grpc.ClientConnInterface) FixtureClient
• type FixtureReply
  • func (*FixtureReply) Descriptor() ([]byte, []int)
  • func (x *FixtureReply) GetMessage() string
  • func (*FixtureReply) ProtoMessage()
  • func (x *FixtureReply) ProtoReflect() protoreflect.Message
  • func (x *FixtureReply) Reset()
  • func (x *FixtureReply) String() string
• type FixtureRequest
  • func (*FixtureRequest) Descriptor() ([]byte, []int)
  • func (x *FixtureRequest) GetName() string
  • func (*FixtureRequest) ProtoMessage()
  • func (x *FixtureRequest) ProtoReflect() protoreflect.Message
  • func (x *FixtureRequest) Reset()
  • func (x *FixtureRequest) String() string
• type FixtureServer
• type Fixture_StreamPingClient
• type Fixture_StreamPingServer
• type Option
• type OptionFn
  • func NoDebugStack() OptionFn
  • func NonErrorCodes(cs ...codes.Code) OptionFn
  • func WithAnalytics(on bool) OptionFn
  • func WithAnalyticsRate(rate float64) OptionFn
  • func WithCustomTag(key string, value interface{}) OptionFn
  • func WithErrorDetailTags() OptionFn
  • func WithIgnoredMetadata(ms ...string) OptionFn
  • func WithMetadataTags() OptionFn
  • func WithRequestTags() OptionFn
  • func WithService(name string) OptionFn
  • func WithSpanOptions(opts ...tracer.StartSpanOption) OptionFn
  • func WithStreamCalls(enabled bool) OptionFn
  • func WithStreamMessages(enabled bool) OptionFn
  • func WithUntracedMethods(ms ...string) OptionFn
• type UnimplementedFixtureServer
  • func (UnimplementedFixtureServer) Ping(context.Context, *FixtureRequest) (*FixtureReply, error)
  • func (UnimplementedFixtureServer) StreamPing(Fixture_StreamPingServer) error
• type UnsafeFixtureServer

Examples

• Package (Client)
• Package (Server)

Constants

const (
	Fixture_Ping_FullMethodName       = "/grpc.Fixture/Ping"
	Fixture_StreamPing_FullMethodName = "/grpc.Fixture/StreamPing"
)

Variables

var File_fixtures_test_proto protoreflect.FileDescriptor

var Fixture_ServiceDesc = grpc.ServiceDesc{
	ServiceName: "grpc.Fixture",
	HandlerType: (*FixtureServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "Ping",
			Handler:    _Fixture_Ping_Handler,
		},
	},
	Streams: []grpc.StreamDesc{
		{
			StreamName:    "StreamPing",
			Handler:       _Fixture_StreamPing_Handler,
			ServerStreams: true,
			ClientStreams: true,
		},
	},
	Metadata: "fixtures_test.proto",
}

Fixture_ServiceDesc is the grpc.ServiceDesc for Fixture service. It's only intended for direct use with grpc.RegisterService, and not to be introspected or modified (even as a copy)

Functions

func NewClientStatsHandler

func NewClientStatsHandler(opts ...Option) stats.Handler

NewClientStatsHandler returns a gRPC client stats.Handler to trace RPC calls.

func NewServerStatsHandler

func NewServerStatsHandler(opts ...Option) stats.Handler

NewServerStatsHandler returns a gRPC server stats.Handler to trace RPC calls.

func RegisterFixtureServer

func RegisterFixtureServer(s grpc.ServiceRegistrar, srv FixtureServer)

func StreamClientInterceptor

func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor

StreamClientInterceptor returns a grpc.StreamClientInterceptor which will trace client streams using the given set of options.

func StreamServerInterceptor

func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor

StreamServerInterceptor will trace streaming requests to the given gRPC server.

func UnaryClientInterceptor

func UnaryClientInterceptor(opts ...Option) grpc.UnaryClientInterceptor

UnaryClientInterceptor returns a grpc.UnaryClientInterceptor which will trace requests using the given set of options.

func UnaryServerInterceptor

func UnaryServerInterceptor(opts ...Option) grpc.UnaryServerInterceptor

UnaryServerInterceptor will trace requests to the given grpc server.

Types

type FixtureClient

type FixtureClient interface {
	Ping(ctx context.Context, in *FixtureRequest, opts ...grpc.CallOption) (*FixtureReply, error)
	StreamPing(ctx context.Context, opts ...grpc.CallOption) (Fixture_StreamPingClient, error)
}

FixtureClient is the client API for Fixture service.

For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.

func NewFixtureClient

func NewFixtureClient(cc grpc.ClientConnInterface) FixtureClient

type FixtureReply

type FixtureReply struct {
	Message string `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
	// contains filtered or unexported fields
}

The response message containing the greetings

func (*FixtureReply) Descriptor

func (*FixtureReply) Descriptor() ([]byte, []int)

Deprecated: Use FixtureReply.ProtoReflect.Descriptor instead.

func (*FixtureReply) GetMessage

func (x *FixtureReply) GetMessage() string

func (*FixtureReply) ProtoMessage

func (*FixtureReply) ProtoMessage()

func (*FixtureReply) ProtoReflect

func (x *FixtureReply) ProtoReflect() protoreflect.Message

func (*FixtureReply) Reset

func (x *FixtureReply) Reset()

func (*FixtureReply) String

func (x *FixtureReply) String() string

type FixtureRequest

type FixtureRequest struct {
	Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
	// contains filtered or unexported fields
}

The request message containing the user's name.

func (*FixtureRequest) Descriptor

func (*FixtureRequest) Descriptor() ([]byte, []int)

Deprecated: Use FixtureRequest.ProtoReflect.Descriptor instead.

func (*FixtureRequest) GetName

func (x *FixtureRequest) GetName() string

func (*FixtureRequest) ProtoMessage

func (*FixtureRequest) ProtoMessage()

func (*FixtureRequest) ProtoReflect

func (x *FixtureRequest) ProtoReflect() protoreflect.Message

func (*FixtureRequest) Reset

func (x *FixtureRequest) Reset()

func (*FixtureRequest) String

func (x *FixtureRequest) String() string

type FixtureServer

type FixtureServer interface {
	Ping(context.Context, *FixtureRequest) (*FixtureReply, error)
	StreamPing(Fixture_StreamPingServer) error
	// contains filtered or unexported methods
}

FixtureServer is the server API for Fixture service. All implementations must embed UnimplementedFixtureServer for forward compatibility

type Fixture_StreamPingClient

type Fixture_StreamPingClient interface {
	Send(*FixtureRequest) error
	Recv() (*FixtureReply, error)
	grpc.ClientStream
}

type Fixture_StreamPingServer

type Fixture_StreamPingServer interface {
	Send(*FixtureReply) error
	Recv() (*FixtureRequest, error)
	grpc.ServerStream
}

type Option

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

Option describes options for the gRPC integration.

type OptionFn

type OptionFn func(*config)

OptionFn represents options applicable to StreamClientInterceptor, UnaryClientInterceptor, StreamServerInterceptor, UnaryServerInterceptor, NewClientStatsHandler and NewServerStatsHandler.

func NoDebugStack

func NoDebugStack() OptionFn

NoDebugStack disables debug stacks for traces with errors. This is useful in situations where errors are frequent, and the overhead of calling debug.Stack may affect performance.

func NonErrorCodes

func NonErrorCodes(cs ...codes.Code) OptionFn

NonErrorCodes determines the list of codes that will not be considered errors in instrumentation. This call overrides the default handling of codes.Canceled as a non-error.

func WithAnalytics

func WithAnalytics(on bool) OptionFn

WithAnalytics enables Trace Analytics for all started spans.

func WithAnalyticsRate

func WithAnalyticsRate(rate float64) OptionFn

WithAnalyticsRate sets the sampling rate for Trace Analytics events correlated to started spans.

func WithCustomTag

func WithCustomTag(key string, value interface{}) OptionFn

WithCustomTag will attach the value to the span tagged by the key.

func WithErrorDetailTags

func WithErrorDetailTags() OptionFn

WithErrorDetailTags specifies whether gRPC responses details contain should be added to spans as tags.

func WithIgnoredMetadata

func WithIgnoredMetadata(ms ...string) OptionFn

WithIgnoredMetadata specifies keys to be ignored while tracing the metadata. Must be used in conjunction with WithMetadataTags.

func WithMetadataTags

func WithMetadataTags() OptionFn

WithMetadataTags specifies whether gRPC metadata should be added to spans as tags.

func WithRequestTags

func WithRequestTags() OptionFn

WithRequestTags specifies whether gRPC requests should be added to spans as tags.

func WithService

func WithService(name string) OptionFn

WithService sets the given service name for the intercepted client.

func WithSpanOptions

func WithSpanOptions(opts ...tracer.StartSpanOption) OptionFn

WithSpanOptions defines a set of additional tracer.StartSpanOption to be added to spans started by the integration.

func WithStreamCalls

func WithStreamCalls(enabled bool) OptionFn

WithStreamCalls enables or disables tracing of streaming calls. This option does not apply to the stats handler.

func WithStreamMessages

func WithStreamMessages(enabled bool) OptionFn

WithStreamMessages enables or disables tracing of streaming messages. This option does not apply to the stats handler.

func WithUntracedMethods

func WithUntracedMethods(ms ...string) OptionFn

WithUntracedMethods specifies full methods to be ignored by the server side and client side interceptors. When a request's full method is in ms, no spans will be created.

type UnimplementedFixtureServer

type UnimplementedFixtureServer struct {
}

UnimplementedFixtureServer must be embedded to have forward compatible implementations.

func (UnimplementedFixtureServer) Ping

func (UnimplementedFixtureServer) Ping(context.Context, *FixtureRequest) (*FixtureReply, error)

func (UnimplementedFixtureServer) StreamPing

func (UnimplementedFixtureServer) StreamPing(Fixture_StreamPingServer) error

type UnsafeFixtureServer

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

UnsafeFixtureServer may be embedded to opt out of forward compatibility for this service. Use of this interface is not recommended, as added methods to FixtureServer will result in compilation errors.