middleware

Documentation

Overview

Package middleware contains gRPC server and client interceptors that wraps unary and streaming RPCs to provide additional functionality.

This package contains the following middlewares:

• Logging server middleware for unary and streaming endpoints.
• Request ID server middleware for unary and streaming endpoints.
• Stream Canceler server middleware for canceling streaming requests.
• Tracing middleware for unary and streaming server and client.
• AWS X-Ray middleware for producing X-Ray segments for unary and streaming client and server.

Example to use the server middleware:

srv := grpc.NewServer(middleware.UnaryRequestID())

Example to use the client middleware:

conn, err := grpc.Dial(host,
    grpc.WithUnaryInterceptor(middleware.UnaryClientTrace()),
    grpc.WithStreamInterceptor(middleware.StreamClientTrace()),
)

Index

• Constants
• func DiscardFromTrace(discard *regexp.Regexp) middleware.TraceOption
• func MaxSamplingRate(r int) middleware.TraceOption
• func MetadataValue(md metadata.MD, key string) string
• func SampleSize(s int) middleware.TraceOption
• func SamplingPercent(p int) middleware.TraceOption
• func SpanIDFunc(f middleware.IDFunc) middleware.TraceOption
• func StreamCanceler(ctx context.Context) grpc.StreamServerInterceptor
• func StreamClientTrace() grpc.StreamClientInterceptor
• func StreamRequestID(options ...middleware.RequestIDOption) grpc.StreamServerInterceptor
• func StreamServerLog(l middleware.Logger) grpc.StreamServerInterceptor
• func StreamServerLogContext(logFromCtx func(context.Context) middleware.Logger) grpc.StreamServerInterceptor
• func StreamServerTrace(opts ...middleware.TraceOption) grpc.StreamServerInterceptor
• func TraceIDFunc(f middleware.IDFunc) middleware.TraceOption
• func UnaryClientTrace() grpc.UnaryClientInterceptor
• func UnaryRequestID(options ...middleware.RequestIDOption) grpc.UnaryServerInterceptor
• func UnaryServerLog(l middleware.Logger) grpc.UnaryServerInterceptor
• func UnaryServerLogContext(logFromCtx func(context.Context) middleware.Logger) grpc.UnaryServerInterceptor
• func UnaryServerTrace(opts ...middleware.TraceOption) grpc.UnaryServerInterceptor
• func UseXRequestIDMetadataOption(f bool) middleware.RequestIDOption
• func XRequestMetadataLimitOption(limit int) middleware.RequestIDOption
• type WrappedServerStream
  • func NewWrappedServerStream(ctx context.Context, ss grpc.ServerStream) *WrappedServerStream
  • func (w *WrappedServerStream) Context() context.Context

Constants

const (
	// TraceIDMetadataKey is the default name of the gRPC request metadata
	// key containing the current TraceID if any.
	TraceIDMetadataKey = "trace-id"

	// ParentSpanIDMetadataKey is the default name of the gRPC request metadata
	// key containing the parent span ID if any.
	ParentSpanIDMetadataKey = "parent-span-id"

	// SpanIDMetadataKey is the default name of the gRPC request metadata
	// containing the span ID if any.
	SpanIDMetadataKey = "span-id"
)

const (
	// RequestIDMetadataKey is the key containing the request ID in the gRPC
	// metadata.
	RequestIDMetadataKey = "x-request-id"
)

Functions

func DiscardFromTrace

func DiscardFromTrace(discard *regexp.Regexp) middleware.TraceOption

DiscardFromTrace adds a regular expression for matching a request path to be discarded from tracing. see middleware.DiscardFromTrace() for more details.

func MaxSamplingRate

func MaxSamplingRate(r int) middleware.TraceOption

MaxSamplingRate is a wrapper for the top-level MaxSamplingRate.

func MetadataValue

func MetadataValue(md metadata.MD, key string) string

MetadataValue returns the first value for the given metadata key if key exists, else returns an empty string.

func SampleSize

func SampleSize(s int) middleware.TraceOption

SampleSize is a wrapper for the top-level SampleSize.

func SamplingPercent

func SamplingPercent(p int) middleware.TraceOption

SamplingPercent is a wrapper for the top-level SamplingPercent.

func SpanIDFunc

func SpanIDFunc(f middleware.IDFunc) middleware.TraceOption

SpanIDFunc is a wrapper for the top-level SpanIDFunc.

func StreamCanceler

func StreamCanceler(ctx context.Context) grpc.StreamServerInterceptor

StreamCanceler provides a middleware that can be used to gracefully stop streaming requests. To stop streaming requests, simply pass in a context with cancellation and cancel the context. When the context given to the StreamCanceler is canceled, it does the following:

1. Stops accepting further streaming requests and returns the code Unavailable with message "server is stopping".
2. Cancels the context of all streaming requests. Your request handler should obey to the cancelation of request context.

Example:

var (
    ctxCancel  context.Context
    cancelFunc context.CancelFunc
)
ctxCancel, cancelFunc = context.WithCancel(parentCtx)
streamInterceptor := StreamCanceler(ctxCancel)
// Use the interceptor in your server and when you need to shutdown
// your server, simply cancel the context given to the StreamCanceler interceptor.
cancelFunc()

// In your application code, look for context cancellation and respond with proper code.
for {
    select {
    case <-ctx.Done():
        return status.Error(codes.Canceled, "canceled")
...

func StreamClientTrace

func StreamClientTrace() grpc.StreamClientInterceptor

StreamClientTrace sets the outgoing stream request metadata with the trace information found in the context so that the downstream service may properly retrieve the parent span ID and trace ID.

Example:

conn, err := grpc.Dial(url, grpc.WithStreamInterceptor(StreamClientTrace()))

func StreamRequestID

func StreamRequestID(options ...middleware.RequestIDOption) grpc.StreamServerInterceptor

StreamRequestID returns a middleware for streaming gRPC requests which initializes the stream metadata with a unique value under the RequestIDMetadata key. Optionally, it uses the incoming "x-request-id" request metadata key, if present, with or without a length limit to use as request ID. The default behavior is to always generate a new ID.

examples of use:

grpc.NewServer(grpc.UnaryInterceptor(middleware.StreamRequestID()))

// enable options for using "x-request-id" metadata key with length limit.
grpc.NewServer(grpc.UnaryInterceptor(middleware.StreamRequestID(
  middleware.UseXRequestIDMetadataOption(true),
  middleware.XRequestMetadataLimitOption(128))))

func StreamServerLog

func StreamServerLog(l middleware.Logger) grpc.StreamServerInterceptor

StreamServerLog returns a middleware that logs incoming streaming gRPC requests and responses. The middleware uses the request ID set by the RequestID middleware or creates a short unique request ID if missing for each incoming request and logs it with the request and corresponding response details.

func StreamServerLogContext

func StreamServerLogContext(logFromCtx func(context.Context) middleware.Logger) grpc.StreamServerInterceptor

StreamServerLogContext returns a middleware that logs incoming streaming gRPC requests and responses similar to StreamServerLog but uses the stream context to extract the logger.

func StreamServerTrace

func StreamServerTrace(opts ...middleware.TraceOption) grpc.StreamServerInterceptor

StreamServerTrace returns a server trace middleware that initializes the trace information in the streaming gRPC request context.

Example:

grpc.NewServer(grpc.StreamInterceptor(middleware.StreamServerTrace()))

// enable options
grpc.NewServer(grpc.StreamInterceptor(middleware.StreamServerTrace(
  middleware.TraceIDFunc(myTraceIDFunc),
  middleware.SpanIDFunc(mySpanIDFunc),
  middleware.MaxSamplingRate(50)))

func TraceIDFunc

func TraceIDFunc(f middleware.IDFunc) middleware.TraceOption

TraceIDFunc is a wrapper for the top-level TraceIDFunc.

func UnaryClientTrace

func UnaryClientTrace() grpc.UnaryClientInterceptor

UnaryClientTrace sets the outgoing unary request metadata with the trace information found in the context so that the downstream service may properly retrieve the parent span ID and trace ID.

Example:

conn, err := grpc.Dial(url, grpc.WithUnaryInterceptor(UnaryClientTrace()))

func UnaryRequestID

func UnaryRequestID(options ...middleware.RequestIDOption) grpc.UnaryServerInterceptor

UnaryRequestID returns a middleware for unary gRPC requests which initializes the request metadata with a unique value under the RequestIDMetadata key. Optionally, it uses the incoming "x-request-id" request metadata key, if present, with or without a length limit to use as request ID. The default behavior is to always generate a new ID.

examples of use:

grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryRequestID()))

// enable options for using "x-request-id" metadata key with length limit.
grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryRequestID(
  middleware.UseXRequestIDMetadataOption(true),
  middleware.XRequestMetadataLimitOption(128))))

func UnaryServerLog

func UnaryServerLog(l middleware.Logger) grpc.UnaryServerInterceptor

UnaryServerLog returns a middleware that logs incoming gRPC requests and outgoing responses. The middleware uses the request ID set by the RequestID middleware or creates a short unique request ID if missing for each incoming request and logs it with the request and corresponding response details.

The middleware logs the incoming requests gRPC method. It also logs the response gRPC status code, message length (in bytes), and timing information.

func UnaryServerLogContext

func UnaryServerLogContext(logFromCtx func(context.Context) middleware.Logger) grpc.UnaryServerInterceptor

UnaryServerLogContext returns a middleware that logs incoming gRPC requests and outgoing responses similar to UnaryServerLog but uses the request context to extract the logger.

func UnaryServerTrace

func UnaryServerTrace(opts ...middleware.TraceOption) grpc.UnaryServerInterceptor

UnaryServerTrace returns a server trace middleware that initializes the trace informartion in the unary gRPC request context.

Example:

grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryServerTrace()))

// enable options
grpc.NewServer(grpc.UnaryInterceptor(middleware.UnaryServerTrace(
  middleware.TraceIDFunc(myTraceIDFunc),
  middleware.SpanIDFunc(mySpanIDFunc),
  middleware.SamplingPercent(100)))

func UseXRequestIDMetadataOption

func UseXRequestIDMetadataOption(f bool) middleware.RequestIDOption

UseXRequestIDMetadataOption enables/disables using "x-request-id" metadata.

func XRequestMetadataLimitOption

func XRequestMetadataLimitOption(limit int) middleware.RequestIDOption

XRequestMetadataLimitOption sets the option for limiting "x-request-id" metadata length.

Types

type WrappedServerStream

type WrappedServerStream struct {
	grpc.ServerStream
	// contains filtered or unexported fields
}

WrappedServerStream overrides the Context() method of the grpc.ServerStream interface.

func NewWrappedServerStream

func NewWrappedServerStream(ctx context.Context, ss grpc.ServerStream) *WrappedServerStream

NewWrappedServerStream returns a new wrapped grpc ServerStream.

func (*WrappedServerStream) Context

func (w *WrappedServerStream) Context() context.Context

Context returns the context for the server stream.