middleware

package
v3.19.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2024 License: MIT Imports: 13 Imported by: 113

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

This section is empty.

Variables

View Source
var (
	// RequestIDKey is the request context key used to store the request ID
	// created by the RequestID middleware.
	RequestIDKey = "goa-request-id"

	// TraceIDKey is the request context key used to store the current Trace
	// ID if any.
	TraceIDKey = "goa-trace-id"

	// TraceSpanIDKey is the request context key used to store the current
	// trace span ID if any.
	TraceSpanIDKey = "goa-trace-span-id"

	// TraceParentSpanIDKey is the request context key used to store the current
	// trace parent span ID if any.
	TraceParentSpanIDKey = "goa-trace-parent-span-id"
)

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 ...any) 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 RequestIDHeaderOption added in v3.8.5

func RequestIDHeaderOption(name string) RequestIDOption

RequestIDHeaderOption sets the name of the header used to capture the incoming request ID. This option also automatically enabled the use of that header.

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.

func (*RequestIDOptions) RequestIDHeader added in v3.8.5

func (o *RequestIDOptions) RequestIDHeader() string

RequestIDHeader returns the request ID header 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 added in v3.0.7

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 added in v3.0.7

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL