goa: github.com/raphael/goa/middleware Index | Files | Directories

package middleware

import "github.com/raphael/goa/middleware"

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

Package Files

ctxkeys.go doc.go log.go requestid.go sampler.go trace.go

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
)

func GenerateRequestID Uses

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 Uses

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

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

type IDFunc Uses

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 Uses

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 Uses

func NewLogger(l *log.Logger) Logger

NewLogger creates a Logger backed by a stdlib logger.

func WrapLogger Uses

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 Uses

type RequestIDOption func(*RequestIDOptions) *RequestIDOptions

RequestIDOption uses a constructor pattern to customize middleware.

func RequestIDLimitOption Uses

func RequestIDLimitOption(limit int) RequestIDOption

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

func UseRequestIDOption Uses

func UseRequestIDOption(f bool) RequestIDOption

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

type RequestIDOptions Uses

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

RequestIDOptions is the struct storing all the options.

func NewRequestIDOptions Uses

func NewRequestIDOptions(options ...RequestIDOption) *RequestIDOptions

NewRequestIDOptions initializes the options for the request ID middleware.

func (*RequestIDOptions) IsUseRequestID Uses

func (o *RequestIDOptions) IsUseRequestID() bool

IsUseRequestID returns the request ID option.

type Sampler Uses

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 Uses

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 Uses

func NewFixedSampler(samplingPercent int) Sampler

NewFixedSampler sets the tracing sampling rate as a percentage value.

type TraceOption Uses

type TraceOption func(*TraceOptions) *TraceOptions

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

func DiscardFromTrace Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

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

func NewTraceOptions Uses

func NewTraceOptions(opts ...TraceOption) *TraceOptions

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

func (*TraceOptions) Discards Uses

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 Uses

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 Uses

func (o *TraceOptions) SpanID() string

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

func (*TraceOptions) TraceID Uses

func (o *TraceOptions) TraceID() string

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

Directories

PathSynopsis
xrayPackage xray contains the AWS X-Ray segment document type populated by the transport-specific X-Ray middleware.
xray/xraytestPackage xraytest contains test helpers for package xray that are used by transport-specific X-Ray middleware tests.

Package middleware imports 12 packages (graph). Updated 2019-10-30. Refresh now. Tools for package owners.