otelmiddleware

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

• func Trace(next http.Handler) http.Handler
• func TraceWithOptions(opt ...TraceOption) func(next http.Handler) http.Handler
• type TraceOption
  • func WithAttributes(attributes ...attribute.KeyValue) TraceOption
  • func WithPropagator(p propagation.TextMapPropagator) TraceOption
  • func WithServiceName(serviceName string) TraceOption
  • func WithTracer(tracer trace.Tracer) TraceOption

Examples

• Trace
• TraceWithOptions
• WithAttributes
• WithPropagator
• WithServiceName
• WithTracer

Functions

func Trace

func Trace(next http.Handler) http.Handler

Trace uses the TraceWithOptions without additional options, this is a shorthand for TraceWithOptions().

Example

package main

import (
	"github.com/vincentfree/opentelemetry-http/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))
}

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-http/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))
}

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-http/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))
}

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-http/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))
}

func WithServiceName

func WithServiceName(serviceName string) TraceOption

WithServiceName is a TraceOption to inject your own serviceName.

Example

package main

import (
	"github.com/vincentfree/opentelemetry-http/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))
}

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-http/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))
}