Documentation ¶
Overview ¶
Package otelmiddleware provides middleware for wrapping http.Server handlers with Open Telemetry tracing support.
The trace.Span is decorated with standard metadata extracted from the http.Request injected into the middleware. the basic information is extracted using the OpenTelemetry semconv package.
When a span gets initialized, it uses the following slice of trace.SpanStartOption
opts := []trace.SpanStartOption{ trace.WithAttributes(semconv.NetAttributesFromHTTPRequest("tcp", request)...), trace.WithAttributes(semconv.EndUserAttributesFromHTTPRequest(request)...), trace.WithAttributes(semconv.HTTPServerAttributesFromHTTPRequest(request.Host, extractRoute(request.RequestURI), request)...), trace.WithSpanKind(trace.SpanKindServer), }
The slice can be extended using the WithAttributes TraceOption function.
After these options are applied, a new span is created and the middleware will pass the http.ResponseWriter and http.Request to the next http.Handler.
Functions
func TraceWithOptions(opt ...TraceOption) func(next http.Handler) http.Handler func Trace(next http.Handler) http.Handler func WithAttributes(attributes ...attribute.KeyValue) TraceOption func WithPropagator(p propagation.TextMapPropagator) TraceOption func WithServiceName(serviceName string) TraceOption func WithTracer(tracer trace.Tracer) TraceOption
Types
type TraceOption func(*traceConfig)
Structs
type traceConfig struct { tracer trace.Tracer propagator propagation.TextMapPropagator attributes []attribute.KeyValue serviceName string }
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Trace ¶
Trace uses the TraceWithOptions without additional options, this is a shorthand for TraceWithOptions().
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { http.Handle("/", otelmiddleware.Trace(eh)) }
Output:
func TraceWithOptions ¶
func TraceWithOptions(opt ...TraceOption) func(next http.Handler) http.Handler
TraceWithOptions takes TraceOption's and initializes a new trace.Span.
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { // returns a function that excepts a http.Handler. handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithServiceName("exampleService")) // pass a http.Handler to extend it with Tracing functionality. http.Handle("/", handler(eh)) }
Output:
Types ¶
type TraceOption ¶
type TraceOption func(*traceConfig)
TraceOption takes a traceConfig struct and applies changes. It can be passed to the TraceWithOptions function to configure a traceConfig struct.
func WithAttributes ¶
func WithAttributes(attributes ...attribute.KeyValue) TraceOption
WithAttributes is a TraceOption to inject your own attributes. Attributes are applied to the trace.Span.
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "go.opentelemetry.io/otel/attribute" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { // returns a function that excepts a http.Handler. handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithAttributes(attribute.String("example", "value"))) // pass a http.Handler to extend it with Tracing functionality. http.Handle("/", handler(eh)) }
Output:
func WithPropagator ¶
func WithPropagator(p propagation.TextMapPropagator) TraceOption
WithPropagator is a TraceOption to inject your own propagation.
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "go.opentelemetry.io/otel" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { // returns a function that excepts a http.Handler. handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithPropagator(otel.GetTextMapPropagator())) // pass a http.Handler to extend it with Tracing functionality. http.Handle("/", handler(eh)) }
Output:
func WithServiceName ¶
func WithServiceName(serviceName string) TraceOption
WithServiceName is a TraceOption to inject your own serviceName.
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { // returns a function that excepts a http.Handler. handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithServiceName("exampleService")) // pass a http.Handler to extend it with Tracing functionality. http.Handle("/", handler(eh)) }
Output:
func WithTracer ¶
func WithTracer(tracer trace.Tracer) TraceOption
WithTracer is a TraceOption to inject your own trace.Tracer.
Example ¶
package main import ( "github.com/vincentfree/opentelemetry/otelmiddleware" "go.opentelemetry.io/otel" "net/http" ) type exampleHandler func(http.ResponseWriter, *http.Request) func (th exampleHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { th(w, r) } var eh = exampleHandler(func(w http.ResponseWriter, r *http.Request) { _, _ = w.Write([]byte("Hello World")) }) func main() { // returns a function that excepts a http.Handler. handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithTracer(otel.Tracer("example-tracer"))) // pass a http.Handler to extend it with Tracing functionality. http.Handle("/", handler(eh)) }
Output:
type WrapResponseWriter ¶ added in v0.1.0
type WrapResponseWriter interface { http.ResponseWriter // Status returns the HTTP status of the request, or 0 if one has not // yet been sent. Status() int // BytesWritten returns the total number of bytes sent to the client. BytesWritten() int // Tee causes the response body to be written to the given io.Writer in // addition to proxying the writes through. Only one io.Writer can be // tee'd to at once: setting a second one will overwrite the first. // Writes will be sent to the proxy before being written to this // io.Writer. It is illegal for the tee'd writer to be modified // concurrently with writes. Tee(io.Writer) // Unwrap returns the original proxied target. Unwrap() http.ResponseWriter // Discard causes all writes to the original ResponseWriter be discarded, // instead writing only to the tee'd writer if it's set. // The caller is responsible for calling WriteHeader and Write on the // original ResponseWriter once the processing is done. Discard() }
WrapResponseWriter is a proxy around an http.ResponseWriter that allows you to hook into various parts of the response process.
func NewWrapResponseWriter ¶ added in v0.1.0
func NewWrapResponseWriter(w http.ResponseWriter, protoMajor int) WrapResponseWriter
NewWrapResponseWriter wraps an http.ResponseWriter, returning a proxy that allows you to hook into various parts of the response process.