grpc

README

GRPC module

How to use

go get github.com/tel-io/instrumentation/middleware/grpc@latest

Client

import (
	//...
    "github.com/tel-io/tel/v2"
    grpcx "github.com/tel-io/instrumentation/middleware/grpc"
    //...
)

func NewConn(addr string)  {
	conn, err := grpc.Dial(addr, grpc.WithTransportCredentials(
		insecure.NewCredentials()),
		// for unary use tel module
		grpc.WithChainUnaryInterceptor(grpcx.UnaryClientInterceptorAll()),
		// for stream use stand-alone trace + metrics no recover
		grpc.WithChainStreamInterceptor(grpcx.StreamClientInterceptor(
			grpcx.WithMetricOption(
				otelgrpc.WithServerHandledHistogram(true),
				otelgrpc.WithConstLabels(
					attribute.String("xxx", "example"),
					attribute.String("yyy", "client"),
				)),
		)),
		grpc.WithBlock(),
	)

    //...
}

Server

    import (

    "github.com/tel-io/tel/v2"
    grpcx "github.com/tel-io/instrumentation/middleware/grpc"
)

func Start(ctx context.Context, addr string) error {
	lis, err := net.Listen("tcp", addr)
	if err != nil {
		return errors.WithMessagef(err, "failed to listen: %v", err)
	}

	otmetr := []otelgrpc.Option{
		otelgrpc.WithServerHandledHistogram(true),
		otelgrpc.WithConstLabels(
			attribute.String("userID", "e64916d9-bfd0-4f79-8ee3-847f2d034d20"),
			attribute.String("xxx", "example"),
			attribute.String("yyy", "server"),
		),
	}

	s := grpc.NewServer(
		// for unary use tel module
		grpc.ChainUnaryInterceptor(grpcx.UnaryServerInterceptorAll(
			grpcx.WithTel(tel.FromCtx(ctx)),
			grpcx.WithMetricOption(otmetr...),
		)),
		// for stream use stand-alone trace + metrics no recover
		grpc.ChainStreamInterceptor(grpcx.StreamServerInterceptor(grpcx.WithTel(tel.FromCtx(ctx)),
			grpcx.WithMetricOption(otmetr...),
		)),
	)

	api.RegisterHelloServiceServer(s, &server{})

	go func() {
		<-ctx.Done()
		tel.FromCtx(ctx).Info("grpc down")

		s.Stop()
	}()

	return errors.WithStack(s.Serve(lis))
}

Documentation

Index

• Variables
• func NewGrpcClientChecker(conn *grpc.ClientConn) health.Checker
• func StreamClientInterceptor(opts ...Option) grpc.StreamClientInterceptor
• func StreamServerInterceptor(opts ...Option) grpc.StreamServerInterceptor
• func UnaryClientInterceptor(o ...Option) grpc.UnaryClientInterceptor
• func UnaryClientInterceptorAll(o ...Option) grpc.UnaryClientInterceptor
• func UnaryServerInterceptor(o ...Option) grpc.UnaryServerInterceptor
• func UnaryServerInterceptorAll(o ...Option) grpc.UnaryServerInterceptor
• type Option
  • func WithIgnoreList(ignore []string) Option
  • func WithMetricOption(option ...otelgrpc.Option) Option
  • func WithTel(t *tel.Telemetry) Option
  • func WithTracerOption(opts ...otracer.Option) Option

Variables

var ErrGrpcInternal = status.New(codes.Internal, "internal server error").Err()

Functions

func NewGrpcClientChecker

func NewGrpcClientChecker(conn *grpc.ClientConn) health.Checker

func StreamClientInterceptor

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

func StreamServerInterceptor

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

func UnaryClientInterceptor

func UnaryClientInterceptor(o ...Option) grpc.UnaryClientInterceptor

UnaryClientInterceptor input ctx assume that it contain telemetry instance as well as invoker already under our telemetry UnaryClientInterceptor implement:

• recovery
• detail log during errors (+ in recovery also)
• measure execution time

func UnaryClientInterceptorAll

func UnaryClientInterceptorAll(o ...Option) grpc.UnaryClientInterceptor

UnaryClientInterceptorAll setup recovery, metrics, tracing and debug option according goal of our framework Execution order:

• opentracing injection via otgrpc.OpenTracingClientInterceptor
• recovery, measure execution time + debug log via own UnaryClientInterceptor
• metrics via metrics.UnaryClientInterceptor

func UnaryServerInterceptor

func UnaryServerInterceptor(o ...Option) grpc.UnaryServerInterceptor

UnaryServerInterceptor the most important create new telepresence instance + fill trace ids

implements:
* new telepresence instance
* fill trace ids
* recovery
* detail log during errors (+ in recovery also)
* measure execution time

func UnaryServerInterceptorAll

func UnaryServerInterceptorAll(o ...Option) grpc.UnaryServerInterceptor

UnaryServerInterceptorAll setup recovery, metrics, tracing and debug option according goal of our framework Execution order:otracer

• opentracing injection via otgrpc.OpenTracingServerInterceptor
• ctx new instance, recovery, measure execution time + debug log via own UnaryServerInterceptor
• metrics via metrics.UnaryServerInterceptor

Types

type Option

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

Option interface used for setting optional config properties.

func WithIgnoreList

func WithIgnoreList(ignore []string) Option

func WithMetricOption

func WithMetricOption(option ...otelgrpc.Option) Option

WithMetricOption overwrite already existed options

func WithTel

func WithTel(t *tel.Telemetry) Option

func WithTracerOption

func WithTracerOption(opts ...otracer.Option) Option

WithTracerOption overwrite already existed options