Merge pull request #7 from vincentfree/add-examples

Add examples

README.md

@@ -1,7 +1,12 @@
-# opentelemetry-http
+# OpenTelemetry http
+
+[![Go](https://github.com/vincentfree/opentelemetry-http/actions/workflows/go.yml/badge.svg)](https://github.com/vincentfree/opentelemetry-http/actions/workflows/go.yml)
+[![CodeQL](https://github.com/vincentfree/opentelemetry-http/actions/workflows/codeql.yml/badge.svg)](https://github.com/vincentfree/opentelemetry-http/actions/workflows/codeql.yml)
+[![Dependency Review](https://github.com/vincentfree/opentelemetry-http/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/vincentfree/opentelemetry-http/actions/workflows/dependency-review.yml)
+[![Go Reference](https://pkg.go.dev/badge/github.com/vincentfree/opentelemetry-http/otelmiddleware.svg)](https://pkg.go.dev/github.com/vincentfree/opentelemetry-http/otelmiddleware)
 
 Open Telemetry http middleware. This package provides an instrumentation for middleware that can be used to trace HTTP requests.
 
 ## version
 
-`0.0.4`
+`0.0.5`

otelmiddleware/doc.go

@@ -7,44 +7,33 @@ 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),
+		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
+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
+Types
 	type TraceOption func(*traceConfig)
 
-# Structs
+Structs
 	type traceConfig struct {
 		tracer trace.Tracer
 		propagator propagation.TextMapPropagator
 		attributes []attribute.KeyValue
 		serviceName string
 	}
-
-
-# Examples
-	// create a new ServeMux
-	serve := http.NewServeMux()
-	// add a new route to the ServeMux
-	serve.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		w.Write([]byte("Hello World"))
-	}))
-	// create the Trace middleware and decorate the ServeMux routes with this middleware.
-	handler := TraceWithOptions(WithServiceName("ExampleService"))(serve)
-	http.ListenAndServe(":8080", handler)
-
 */
 package otelmiddleware

otelmiddleware/example_test.go

@@ -1,23 +1,59 @@
 package otelmiddleware_test
 
 import (
-	"log"
+	"github.com/vincentfree/opentelemetry-http/otelmiddleware"
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/attribute"
 	"net/http"
+)
 
-	"github.com/vincentfree/opentelemetry-http/otelmiddleware"
+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 Example() {
-	// create a new ServeMux
-	serve := http.NewServeMux()
-	// add a new route to the ServeMux
-	serve.Handle("/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		_, err := w.Write([]byte("Hello World"))
-		if err != nil {
-			// handle error
-		}
-	}))
-	// create the Trace middleware and decorate the ServeMux routes with this middleware.
-	handler := otelmiddleware.TraceWithOptions(otelmiddleware.WithServiceName("ExampleService"))(serve)
-	log.Fatal(http.ListenAndServe(":8080", handler))
+func ExampleWithTracer() {
+	// 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))
+}
+
+func ExampleWithServiceName() {
+	// 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 ExampleWithAttributes() {
+	// 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 ExampleWithPropagator() {
+	// 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 ExampleTraceWithOptions() {
+	// 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 ExampleTrace() {
+	http.Handle("/", otelmiddleware.Trace(eh))
 }