Documentation

Overview

    Package middleware contains transport independent middlewares. A middleware is a function that accepts a endpoint function and returns another endpoint function. The middleware should invoke the endpoint function given as argument and may apply additional transformations prior to and after calling the original. The middlewares included in this package include a logger middleware to log incoming requests, a request ID middleware that makes sure every request as a unique ID stored in the context and a couple of middlewares used to implement tracing.

    Index

    Constants

    View Source
    const (
    	// RequestIDKey is the request context key used to store the request ID
    	// created by the RequestID middleware.
    	RequestIDKey ctxKey = iota + 1
    
    	// TraceIDKey is the request context key used to store the current Trace
    	// ID if any.
    	TraceIDKey
    
    	// TraceSpanIDKey is the request context key used to store the current
    	// trace span ID if any.
    	TraceSpanIDKey
    
    	// TraceParentSpanIDKey is the request context key used to store the current
    	// trace parent span ID if any.
    	TraceParentSpanIDKey
    )

    Variables

    This section is empty.

    Functions

    func GenerateRequestID

    func GenerateRequestID(ctx context.Context, o *RequestIDOptions) context.Context

      GenerateRequestID initializes the given context with a unique value under the RequestIDKey key. If UseRequestIDOption is set to true, it uses the RequestIDKey key in the context (if present) instead of generating a new ID.

      func WithSpan

      func WithSpan(ctx context.Context, traceID, spanID, parentID string) context.Context

        WithSpan returns a context containing the given trace, span and parent span IDs.

        Types

        type IDFunc

        type IDFunc func() string

          IDFunc is a function that produces span and trace IDs for consumption by tracing systems such as Zipkin or AWS X-Ray.

          type Logger

          type Logger interface {
          	// Log creates a log entry using a sequence of alternating keys
          	// and values.
          	Log(keyvals ...interface{}) error
          }

            Logger is the logging interface used by the middleware to produce log entries.

            func NewLogger

            func NewLogger(l *log.Logger) Logger

              NewLogger creates a Logger backed by a stdlib logger.

              func WrapLogger

              func WrapLogger(l Logger, traceID string) Logger

                WrapLogger returns a logger which logs the trace ID with every message if there is one.

                type RequestIDOption

                type RequestIDOption func(*RequestIDOptions) *RequestIDOptions

                  RequestIDOption uses a constructor pattern to customize middleware.

                  func RequestIDLimitOption

                  func RequestIDLimitOption(limit int) RequestIDOption

                    RequestIDLimitOption sets the option for truncating the request ID stored in the context at the specified length.

                    func UseRequestIDOption

                    func UseRequestIDOption(f bool) RequestIDOption

                      UseRequestIDOption enables/disables using RequestID context key to store the unique request ID.

                      type RequestIDOptions

                      type RequestIDOptions struct {
                      	// contains filtered or unexported fields
                      }

                        RequestIDOptions is the struct storing all the options.

                        func NewRequestIDOptions

                        func NewRequestIDOptions(options ...RequestIDOption) *RequestIDOptions

                          NewRequestIDOptions initializes the options for the request ID middleware.

                          func (*RequestIDOptions) IsUseRequestID

                          func (o *RequestIDOptions) IsUseRequestID() bool

                            IsUseRequestID returns the request ID option.

                            type Sampler

                            type Sampler interface {
                            	// Sample returns true if the caller should sample now.
                            	Sample() bool
                            }

                              Sampler is an interface for computing when a sample falls within a range.

                              func NewAdaptiveSampler

                              func NewAdaptiveSampler(maxSamplingRate, sampleSize int) Sampler

                                NewAdaptiveSampler computes the interval for sampling for tracing middleware. it can also be used by non-web go routines to trace internal API calls.

                                maxSamplingRate is the desired maximum sampling rate in requests per second.

                                sampleSize sets the number of requests between two adjustments of the sampling rate when MaxSamplingRate is set. the sample rate cannot be adjusted until the sample size is reached at least once.

                                func NewFixedSampler

                                func NewFixedSampler(samplingPercent int) Sampler

                                  NewFixedSampler sets the tracing sampling rate as a percentage value.

                                  type TraceOption

                                  type TraceOption func(*TraceOptions) *TraceOptions

                                    TraceOption is a constructor option that makes it possible to customize the middleware.

                                    func DiscardFromTrace

                                    func DiscardFromTrace(discard *regexp.Regexp) TraceOption

                                      DiscardFromTrace adds a regular expression for matching a request path to be discarded from tracing. this is useful for frequent API calls that are not important to trace, such as health checks. the pattern can be a full or partial match and could even support both HTTP and gRPC paths with an OR expression, etc.

                                      note that discards can be overridden if the incoming request already has a trace ID.

                                      func MaxSamplingRate

                                      func MaxSamplingRate(r int) TraceOption

                                        MaxSamplingRate sets a target sampling rate in requests per second. Setting a max sampling rate causes the middleware to adjust the sampling percent dynamically. Defaults to 2 req/s. SamplingPercent and MaxSamplingRate are mutually exclusive.

                                        func SampleSize

                                        func SampleSize(s int) TraceOption

                                          SampleSize sets the number of requests between two adjustments of the sampling rate when MaxSamplingRate is set. Defaults to 1,000.

                                          func SamplingPercent

                                          func SamplingPercent(p int) TraceOption

                                            SamplingPercent configures the percentage of requests that should be traced. If the incoming request has a Trace ID the sampling rate is disregarded and tracing is enabled. It sets the tracing sampling rate as a percentage value. It panics if p is less than 0 or more than 100. SamplingPercent and MaxSamplingRate are mutually exclusive.

                                            func SpanIDFunc

                                            func SpanIDFunc(f IDFunc) TraceOption

                                              SpanIDFunc configures the function used to compute span IDs. Use this option to generate IDs compatible with backend tracing systems (e.g. AWS XRay).

                                              func TraceIDFunc

                                              func TraceIDFunc(f IDFunc) TraceOption

                                                TraceIDFunc configures the function used to compute trace IDs. Use this option to generate IDs compatible with backend tracing systems (e.g. AWS XRay).

                                                type TraceOptions

                                                type TraceOptions struct {
                                                	// contains filtered or unexported fields
                                                }

                                                  TraceOptions is the struct storing all the options for trace middleware.

                                                  func NewTraceOptions

                                                  func NewTraceOptions(opts ...TraceOption) *TraceOptions

                                                    NewTraceOptions returns the trace middleware options by running the given constructors.

                                                    func (*TraceOptions) Discards

                                                    func (o *TraceOptions) Discards() []*regexp.Regexp

                                                      Discards returns the list of regular expressions used to match paths to be discarded from tracing.

                                                      func (*TraceOptions) NewSampler

                                                      func (o *TraceOptions) NewSampler() Sampler

                                                        NewSampler returns a Sampler. If maxSamplingRate is positive it returns an adaptive sampler or else it returns a fixed sampler.

                                                        func (*TraceOptions) SpanID

                                                        func (o *TraceOptions) SpanID() string

                                                          SpanID returns a new span ID. Use SpanIDFunc to set the function that generates span IDs.

                                                          func (*TraceOptions) TraceID

                                                          func (o *TraceOptions) TraceID() string

                                                            TraceID returns a new trace ID. Use TraceIDFunc to set the function that generates trace IDs.

                                                            Directories

                                                            Path Synopsis
                                                            Package xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.
                                                            Package xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.
                                                            xraytest
                                                            Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.
                                                            Package xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.