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 ¶
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.
Types ¶
type IDFunc ¶ added in v1.2.0
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 WrapLogger ¶
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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 ¶ added in v1.3.0
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.
Source Files
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. |