Documentation
¶
Overview ¶
Package apmhttp provides a tracing middleware http.Handler for servers, and a tracing http.RoundTripper for clients.
Index ¶
- Constants
- func ClientRequestName(req *http.Request) string
- func FormatTraceparentHeader(c elasticapm.TraceContext) string
- func IgnoreNone(*http.Request) bool
- func ParseTraceparentHeader(h string) (elasticapm.TraceContext, error)
- func RequestWithContext(ctx context.Context, req *http.Request) *http.Request
- func ServerRequestName(req *http.Request) string
- func SetTransactionContext(tx *elasticapm.Transaction, req *http.Request, resp *Response, ...)
- func StartTransaction(tracer *elasticapm.Tracer, name string, req *http.Request) (*elasticapm.Transaction, *http.Request)
- func StatusCodeResult(statusCode int) string
- func Wrap(h http.Handler, o ...ServerOption) http.Handler
- func WrapClient(c *http.Client, o ...ClientOption) *http.Client
- func WrapRoundTripper(r http.RoundTripper, o ...ClientOption) http.RoundTripper
- type ClientOption
- type RecoveryFunc
- type RequestIgnorerFunc
- type RequestNameFunc
- type Response
- type ServerOption
Constants ¶
const ( // TraceparentHeader is the HTTP header for trace propagation. // // NOTE: at this time, the W3C Trace-Context headers are not finalised. // To avoid producing possibly invalid traceparent headers, we will // use an alternative name until the format is frozen. TraceparentHeader = "Elastic-Apm-Traceparent" )
Variables ¶
This section is empty.
Functions ¶
func ClientRequestName ¶
ClientRequestName returns the span name for the client request, req.
func FormatTraceparentHeader ¶ added in v0.5.0
func FormatTraceparentHeader(c elasticapm.TraceContext) string
FormatTraceparentHeader formats the given trace context as a traceparent header.
func IgnoreNone ¶ added in v0.5.0
IgnoreNone is a RequestIgnorerFunc which ignores no requests.
func ParseTraceparentHeader ¶ added in v0.5.0
ParseTraceparentHeader parses the given header, which is expected to be in the W3C Trace-Context traceparent format according to W3C Editor's Draft 23 May 2018:
https://w3c.github.io/distributed-tracing/report-trace-context.html#traceparent-field
Note that the returned TraceParent's Trace and Span fields are not necessarily valid. The caller must decide whether or not it wishes to disregard invalid trace/span IDs, and validate them as required using their provided Validate methods.
func RequestWithContext ¶
RequestWithContext is equivalent to req.WithContext, except that the URL pointer is copied, rather than the contents.
func ServerRequestName ¶
ServerRequestName returns the transaction name for the server request, req.
func SetTransactionContext ¶
func SetTransactionContext(tx *elasticapm.Transaction, req *http.Request, resp *Response, body *elasticapm.BodyCapturer, finished bool)
SetTransactionContext sets tx.Result and, if the transaction is being sampled, sets tx.Context with information from req, resp, and finished.
The finished property indicates that the response was not completely written, e.g. because the handler panicked and we did not recover the panic.
func StartTransaction ¶ added in v0.5.0
func StartTransaction(tracer *elasticapm.Tracer, name string, req *http.Request) (*elasticapm.Transaction, *http.Request)
StartTransaction returns a new Transaction with name, created with tracer, and taking trace context from req.
If the transaction is not ignored, the request will be returned with the transaction added to its context.
func StatusCodeResult ¶
StatusCodeResult returns the transaction result value to use for the given status code.
func Wrap ¶
func Wrap(h http.Handler, o ...ServerOption) http.Handler
Wrap returns an http.Handler wrapping h, reporting each request as a transaction to Elastic APM.
By default, the returned Handler will use elasticapm.DefaultTracer. Use WithTracer to specify an alternative tracer.
By default, the returned Handler will recover panics, reporting them to the configured tracer. To override this behaviour, use WithRecovery.
func WrapClient ¶
func WrapClient(c *http.Client, o ...ClientOption) *http.Client
WrapClient returns a new *http.Client with all fields copied across, and the Transport field wrapped with WrapRoundTripper such that client requests are reported as spans to Elastic APM if their context contains a sampled transaction.
If c is nil, then http.DefaultClient is wrapped.
func WrapRoundTripper ¶
func WrapRoundTripper(r http.RoundTripper, o ...ClientOption) http.RoundTripper
WrapRoundTripper returns an http.RoundTripper wrapping r, reporting each request as a span to Elastic APM, if the request's context contains a sampled transaction.
If r is nil, then http.DefaultTransport is wrapped.
Types ¶
type ClientOption ¶
type ClientOption func(*roundTripper)
ClientOption sets options for tracing client requests.
type RecoveryFunc ¶
type RecoveryFunc func( w http.ResponseWriter, req *http.Request, body *elasticapm.BodyCapturer, tx *elasticapm.Transaction, recovered interface{}, )
RecoveryFunc is the type of a function for use in WithRecovery.
func NewTraceRecovery ¶
func NewTraceRecovery(t *elasticapm.Tracer) RecoveryFunc
NewTraceRecovery returns a RecoveryFunc for use in WithRecovery.
The returned RecoveryFunc will report recovered error to Elastic APM using the given Tracer, or elasticapm.DefaultTracer if t is nil. The error will be linked to the given transaction.
type RequestIgnorerFunc ¶
RequestIgnorerFunc is the type of a function for use in WithServerRequestIgnorer.
func DefaultServerRequestIgnorer ¶ added in v0.5.0
func DefaultServerRequestIgnorer() RequestIgnorerFunc
DefaultServerRequestIgnorer returns the default RequestIgnorer to use in handlers. If ELASTIC_APM_IGNORE_URLS is set to a valid regular expression, then it will be used to ignore matching requests; otherwise none are ignored.
func NewRegexpRequestIgnorer ¶ added in v0.5.0
func NewRegexpRequestIgnorer(re *regexp.Regexp) RequestIgnorerFunc
NewRegexpRequestIgnorer returns a RequestIgnorerFunc which matches requests' URLs against re. Note that for server requests, typically only Path and possibly RawQuery will be set, so the regular expression should take this into account.
type RequestNameFunc ¶
RequestNameFunc is the type of a function for use in WithServerRequestName.
type Response ¶
type Response struct {
// StatusCode records the HTTP status code set via WriteHeader.
StatusCode int
// Headers holds the headers set in the ResponseWriter.
Headers http.Header
// HeadersWritten records whether or not headers were written.
HeadersWritten bool
}
Response records details of the HTTP response.
func WrapResponseWriter ¶
func WrapResponseWriter(w http.ResponseWriter) (http.ResponseWriter, *Response)
WrapResponseWriter wraps an http.ResponseWriter and returns the wrapped value along with a *Response which will be filled in when the handler is called. The *Response value must not be inspected until after the request has been handled, to avoid data races.
The returned http.ResponseWriter implements http.Pusher and http.Hijacker if and only if the provided http.ResponseWriter does.
type ServerOption ¶
type ServerOption func(*handler)
ServerOption sets options for tracing server requests.
func WithRecovery ¶
func WithRecovery(r RecoveryFunc) ServerOption
WithRecovery returns a ServerOption which sets r as the recovery function to use for tracing server requests.
func WithServerRequestIgnorer ¶
func WithServerRequestIgnorer(r RequestIgnorerFunc) ServerOption
WithServerRequestIgnorer returns a ServerOption which sets r as the function to use to determine whether or not a server request should be ignored. If r is nil, all requests will be reported.
func WithServerRequestName ¶
func WithServerRequestName(r RequestNameFunc) ServerOption
WithServerRequestName returns a ServerOption which sets r as the function to use to obtain the transaction name for the given server request.
func WithTracer ¶
func WithTracer(t *elasticapm.Tracer) ServerOption
WithTracer returns a ServerOption which sets t as the tracer to use for tracing server requests.
Source Files