middleware

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
• func GenerateRequestID(ctx context.Context, o *RequestIDOptions) context.Context
• func WithSpan(ctx context.Context, traceID, spanID, parentID string) context.Context
• type IDFunc
• type Logger
  • func NewLogger(l *log.Logger) Logger
  • func WrapLogger(l Logger, traceID string) Logger
• type RequestIDOption
  • func RequestIDLimitOption(limit int) RequestIDOption
  • func UseRequestIDOption(f bool) RequestIDOption
• type RequestIDOptions
  • func NewRequestIDOptions(options ...RequestIDOption) *RequestIDOptions
  • func (o *RequestIDOptions) IsUseRequestID() bool
• type Sampler
  • func NewAdaptiveSampler(maxSamplingRate, sampleSize int) Sampler
  • func NewFixedSampler(samplingPercent int) Sampler
• type TraceOption
  • func DiscardFromTrace(discard *regexp.Regexp) TraceOption
  • func MaxSamplingRate(r int) TraceOption
  • func SampleSize(s int) TraceOption
  • func SamplingPercent(p int) TraceOption
  • func SpanIDFunc(f IDFunc) TraceOption
  • func TraceIDFunc(f IDFunc) TraceOption
• type TraceOptions
  • func NewTraceOptions(opts ...TraceOption) *TraceOptions
  • func (o *TraceOptions) Discards() []*regexp.Regexp
  • func (o *TraceOptions) NewSampler() Sampler
  • func (o *TraceOptions) SpanID() string
  • func (o *TraceOptions) TraceID() string

Constants

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
)

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.