Improve docs (#8)

Author: aldas

README.md

@@ -1,7 +1,6 @@
 [![Sourcegraph](https://sourcegraph.com/github.com/labstack/echo-opentelemetry/-/badge.svg?style=flat-square)](https://sourcegraph.com/github.com/labstack/echo-opentelemetry?badge)
 [![GoDoc](http://img.shields.io/badge/go-documentation-blue.svg?style=flat-square)](https://pkg.go.dev/github.com/labstack/echo-opentelemetry)
 [![Go Report Card](https://goreportcard.com/badge/github.com/labstack/echo-opentelemetry?style=flat-square)](https://goreportcard.com/report/github.com/labstack/echo-opentelemetry)
-[![Codecov](https://img.shields.io/codecov/c/github/labstack/echo-opentelemetry.svg?style=flat-square)](https://codecov.io/gh/labstack/echo-opentelemetry)
 [![License](http://img.shields.io/badge/license-mit-blue.svg?style=flat-square)](https://raw.githubusercontent.com/labstack/echo-opentelemetry/main/LICENSE)
 
 # Echo OpenTelemetry (OTel) middleware

extrator.go

@@ -12,10 +12,36 @@ import (
 
 	"go.opentelemetry.io/otel/attribute"
 	"go.opentelemetry.io/otel/metric"
+)
+
+import (
 	semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
 	"go.opentelemetry.io/otel/semconv/v1.39.0/httpconv"
 )
 
+/*
+ Working principles for tracing/metering HTTP requests/responses with extractor.
+
+ 1. Create a Values struct per request served to hold extracted values from Request and Response `v := Values{}`.
+   1.1. If your middleware needs to support default/custom values (server name/port, client addr etc) this is good place
+				to set them.
+ 2. Extract request values from the HTTP request to Values struct `err := v.ExtractRequest(request)`. These extracted values
+		are used to start then span and when metrics are recorded at the end of the request (response side)
+ 3. Create the new span.
+   3.1. Attributes for span can be acquired from extracted values with `attr := v.SpanStartAttributes()`
+   3.2. If your middleware needs to support additional start attributes, add them to attributes from previous step.
+ 4. Execute next handler in chain.
+ 5. Determine if the request / response ended with an error
+ 6. Extract response values from HTTP response to Values struct
+	  6.1. Determine the response status that was sent to the client `v.HTTPResponseStatusCode = ?`
+		6.2. Extract response body size `v.HTTPResponseBodySize = ?`
+ 7. Attributes from response can be acquired from extracted values with `attr := v.SpanEndAttributes()`
+   7.1. If your middleware needs to support additional end attributes, add them to attributes.
+ 8. Create a RecordValues struct for metrics recording `iv := RecordValues{...}`.
+ 9. Record metrics with `m.Record(ctx, iv)`
+ 10. End the span with `span.End(ctx)`
+*/
+
 // Metrics holds a standard set of OpenTelemetry global request/response metrics
 type Metrics struct {
 	// requestDurationHistogram (`http.server.request.duration`) is the duration of HTTP server requests.

otel.go

@@ -89,7 +89,8 @@ type AttributesFunc func(c *echo.Context, v *Values, attr []attribute.KeyValue)
 // MetricAttributesFunc is used to compose attributes for Metrics.Record.
 type MetricAttributesFunc func(c *echo.Context, v *Values) []attribute.KeyValue
 
-// MetricsRecorder is used to record metrics.
+// MetricsRecorder is used to record metrics. This interface is used to allow custom metrics recording with access to
+// the Echo context, so additional attributes can be extracted from it.
 type MetricsRecorder interface {
 	Record(c *echo.Context, v RecordValues)
 }
@@ -239,6 +240,7 @@ func (config Config) ToMiddleware() (echo.MiddlewareFunc, error) {
 				RequestDuration: time.Since(requestStartTime),
 				ExtractedValues: ev,
 				Attributes:      nil,
+				// when Attributes are left nil, they are extracted with `iv.ExtractedValues.MetricAttributes()` inside `metrics.Record()` call
 			}
 			if config.MetricAttributes != nil {
 				iv.Attributes = config.MetricAttributes(c, &ev)
@@ -250,6 +252,7 @@ func (config Config) ToMiddleware() (echo.MiddlewareFunc, error) {
 	}, nil
 }
 
+// echoMetricsRecorder is the default implementation for Echo metric recording interface
 type echoMetricsRecorder struct {
 	*Metrics
 }