otelhttpx

README

Attributions

Code taken from go.opentelemetry.io/contrib

Documentation

Overview

package otelhttpx provides an http.Handler and functions that are intended to be used to add tracing by wrapping existing handlers (with Handler) and routes WithRouteTag.

Index

• Constants
• Variables
• func Get(ctx context.Context, targetURL string) (resp *http.Response, err error)
• func Head(ctx context.Context, targetURL string) (resp *http.Response, err error)
• func NewHandler(handler http.Handler, operation string, opts ...Option) http.Handler
• func NewMiddleware(operation string, opts ...Option) func(http.Handler) http.Handler
• func Post(ctx context.Context, targetURL, contentType string, body io.Reader) (resp *http.Response, err error)
• func PostForm(ctx context.Context, targetURL string, data url.Values) (resp *http.Response, err error)
• func WithRouteTag(route string, h http.Handler) http.Handler
• type Filter
• type Labeler
  • func LabelerFromContext(ctx context.Context) (*Labeler, bool)
  • func (l *Labeler) Add(ls ...attribute.KeyValue)
  • func (l *Labeler) Get() []attribute.KeyValue
• type Option
  • func WithClientTrace(f func(context.Context) *httptrace.ClientTrace) Option
  • func WithFilter(f Filter) Option
  • func WithHTTPServerRequestAttributes(f func(string, *http.Request) []attribute.KeyValue) Option
  • func WithHTTPServerRequestMetricsAttributes(f func(string, *http.Request) []attribute.KeyValue) Option
  • func WithMessageEvents(events ...event) Option
  • func WithMeter(meter metric.Meter) Option
  • func WithMeterProvider(provider metric.MeterProvider) Option
  • func WithPropagators(ps propagation.TextMapPropagator) Option
  • func WithPublicEndpoint() Option
  • func WithPublicEndpointFn(fn func(*http.Request) bool) Option
  • func WithServerName(server string) Option
  • func WithSpanNameFormatter(f func(operation string, r *http.Request) string) Option
  • func WithSpanOptions(opts ...trace.SpanStartOption) Option
  • func WithTracerProvider(provider trace.TracerProvider) Option
• type Transport
  • func NewTransport(base http.RoundTripper, opts ...Option) *Transport
  • func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

Constants

const (
	ReadBytesKey  = attribute.Key("http.read_bytes")  // if anything was read from the request body, the total number of bytes read
	ReadErrorKey  = attribute.Key("http.read_error")  // If an error occurred while reading a request, the string of the error (io.EOF is not recorded)
	WroteBytesKey = attribute.Key("http.wrote_bytes") // if anything was written to the response writer, the total number of bytes written
	WriteErrorKey = attribute.Key("http.write_error") // if an error occurred while writing a reply, the string of the error (io.EOF is not recorded)
)

Attribute keys that can be added to a span.

const (
	ReadEvents event = iota
	WriteEvents
)

Different types of events that can be recorded, see WithMessageEvents.

const ScopeName = "github.com/clinia/x/otelhttpx"

ScopeName is the instrumentation scope name.

Variables

var DefaultClient = &http.Client{Transport: NewTransport(http.DefaultTransport)}

DefaultClient is the default Client and is used by Get, Head, Post and PostForm. Please be careful of intitialization order - for example, if you change the global propagator, the DefaultClient might still be using the old one.

Functions

func Get

func Get(ctx context.Context, targetURL string) (resp *http.Response, err error)

Get is a convenient replacement for http.Get that adds a span around the request.

func Head

func Head(ctx context.Context, targetURL string) (resp *http.Response, err error)

Head is a convenient replacement for http.Head that adds a span around the request.

func NewHandler

func NewHandler(handler http.Handler, operation string, opts ...Option) http.Handler

NewHandler wraps the passed handler in a span named after the operation and enriches it with metrics.

func NewMiddleware

func NewMiddleware(operation string, opts ...Option) func(http.Handler) http.Handler

NewMiddleware returns a tracing and metrics instrumentation middleware. The handler returned by the middleware wraps a handler in a span named after the operation and enriches it with metrics.

func Post

func Post(ctx context.Context, targetURL, contentType string, body io.Reader) (resp *http.Response, err error)

Post is a convenient replacement for http.Post that adds a span around the request.

func PostForm

func PostForm(ctx context.Context, targetURL string, data url.Values) (resp *http.Response, err error)

PostForm is a convenient replacement for http.PostForm that adds a span around the request.

func WithRouteTag

func WithRouteTag(route string, h http.Handler) http.Handler

WithRouteTag annotates spans and metrics with the provided route name with HTTP route attribute.

Types

type Filter

type Filter func(*http.Request) bool

Filter is a predicate used to determine whether a given http.request should be traced. A Filter must return true if the request should be traced.

type Labeler

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

Labeler is used to allow instrumented HTTP handlers to add custom attributes to the metrics recorded by the net/http instrumentation.

func LabelerFromContext

func LabelerFromContext(ctx context.Context) (*Labeler, bool)

LabelerFromContext retrieves a Labeler instance from the provided context if one is available. If no Labeler was found in the provided context a new, empty Labeler is returned and the second return value is false. In this case it is safe to use the Labeler but any attributes added to it will not be used.

func (*Labeler) Add

func (l *Labeler) Add(ls ...attribute.KeyValue)

Add attributes to a Labeler.

func (*Labeler) Get

func (l *Labeler) Get() []attribute.KeyValue

Get returns a copy of the attributes added to the Labeler.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option interface used for setting optional config properties.

func WithClientTrace

func WithClientTrace(f func(context.Context) *httptrace.ClientTrace) Option

WithClientTrace takes a function that returns client trace instance that will be applied to the requests sent through the otelhttp Transport.

func WithFilter

func WithFilter(f Filter) Option

WithFilter adds a filter to the list of filters used by the handler. If any filter indicates to exclude a request then the request will not be traced. All filters must allow a request to be traced for a Span to be created. If no filters are provided then all requests are traced. Filters will be invoked for each processed request, it is advised to make them simple and fast.

func WithHTTPServerRequestAttributes

func WithHTTPServerRequestAttributes(f func(string, *http.Request) []attribute.KeyValue) Option

WithHTTPServerRequestAttributes allows for custom attributes to be added to the span created for each incoming request.

func WithHTTPServerRequestMetricsAttributes

func WithHTTPServerRequestMetricsAttributes(f func(string, *http.Request) []attribute.KeyValue) Option

WithHTTPServerRequestMetricsAttributes allows for custom attributes to be added to the metric created for each incoming request.

func WithMessageEvents

func WithMessageEvents(events ...event) Option

WithMessageEvents configures the Handler to record the specified events (span.AddEvent) on spans. By default only summary attributes are added at the end of the request.

Valid events are:

• ReadEvents: Record the number of bytes read after every http.Request.Body.Read using the ReadBytesKey
• WriteEvents: Record the number of bytes written after every http.ResponeWriter.Write using the WriteBytesKey

func WithMeter

func WithMeter(meter metric.Meter) Option

WithMeter specifies a meter to use for creating metrics.

func WithMeterProvider

func WithMeterProvider(provider metric.MeterProvider) Option

WithMeterProvider specifies a meter provider to use for creating a meter. If none is specified, the global provider is used.

func WithPropagators

func WithPropagators(ps propagation.TextMapPropagator) Option

WithPropagators configures specific propagators. If this option isn't specified, then the global TextMapPropagator is used.

func WithPublicEndpoint

func WithPublicEndpoint() Option

WithPublicEndpoint configures the Handler to link the span with an incoming span context. If this option is not provided, then the association is a child association instead of a link.

func WithPublicEndpointFn

func WithPublicEndpointFn(fn func(*http.Request) bool) Option

WithPublicEndpointFn runs with every request, and allows conditionnally configuring the Handler to link the span with an incoming span context. If this option is not provided or returns false, then the association is a child association instead of a link. Note: WithPublicEndpoint takes precedence over WithPublicEndpointFn.

func WithServerName

func WithServerName(server string) Option

WithServerName returns an Option that sets the name of the (virtual) server handling requests.

func WithSpanNameFormatter

func WithSpanNameFormatter(f func(operation string, r *http.Request) string) Option

WithSpanNameFormatter takes a function that will be called on every request and the returned string will become the Span Name.

func WithSpanOptions

func WithSpanOptions(opts ...trace.SpanStartOption) Option

WithSpanOptions configures an additional set of trace.SpanOptions, which are applied to each new span.

func WithTracerProvider

func WithTracerProvider(provider trace.TracerProvider) Option

WithTracerProvider specifies a tracer provider to use for creating a tracer. If none is specified, the global provider is used.

type Transport

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

Transport implements the http.RoundTripper interface and wraps outbound HTTP(S) requests with a span and enriches it with metrics.

func NewTransport

func NewTransport(base http.RoundTripper, opts ...Option) *Transport

NewTransport wraps the provided http.RoundTripper with one that starts a span, injects the span context into the outbound request headers, and enriches it with metrics.

If the provided http.RoundTripper is nil, http.DefaultTransport will be used as the base http.RoundTripper.

func (*Transport) RoundTrip

func (t *Transport) RoundTrip(r *http.Request) (*http.Response, error)

RoundTrip creates a Span and propagates its context via the provided request's headers before handing the request to the configured base RoundTripper. The created span will end when the response body is closed or when a read from the body returns io.EOF.