Documentation
¶
Overview ¶
Package trace provides stable request trace and correlation middleware.
The middleware propagates request and trace identifiers through context and response headers so logs, Problem Details responses, and downstream calls can be correlated without coupling handlers to a tracing provider.
Purpose: See the package summary above. Import: `github.com/aatuh/api-toolkit/v4/middleware/trace`. Example: See docs/api-reference.md for package example links and docs/cookbook.md for task recipes. Errors: Constructors, parsers, and handlers return or write documented errors according to their signatures; packages with plain data types do not add hidden error channels. Concurrency: Treat configured middleware and helpers as immutable after construction; request and response values remain request-scoped unless a type documents stronger guarantees. Stability: Stable core API under VERSIONING.md and scripts/apicheck.sh. When not to use: Prefer net/http, application-owned types, or narrower helpers when this package contract is not needed.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetTraceID ¶
GetTraceID returns the hex-encoded 16-byte trace id if present.
Types ¶
type Middleware ¶
type Middleware struct {
// contains filtered or unexported fields
}
Middleware attaches trace/span IDs to request context and sets response header.
func New ¶
func New(opts Options) (*Middleware, error)
New constructs a Middleware with sane defaults.
Example ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"github.com/aatuh/api-toolkit/v4/middleware/trace"
)
type exampleIDGen struct {
value string
}
func (g exampleIDGen) New() string { return g.value }
func main() {
middleware, err := trace.New(trace.Options{
TraceIDGen: exampleIDGen{value: "11111111111111111111111111111111"},
SpanIDGen: exampleIDGen{value: "2222222222222222"},
})
if err != nil {
panic(err)
}
var gotTraceID string
handler := middleware.Middleware()(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
gotTraceID = trace.GetTraceID(r)
w.WriteHeader(http.StatusNoContent)
}))
recorder := httptest.NewRecorder()
req := httptest.NewRequestWithContext(context.Background(), http.MethodGet, "/widgets", nil)
handler.ServeHTTP(recorder, req)
fmt.Println(gotTraceID)
}
Output: 11111111111111111111111111111111
func (*Middleware) Middleware ¶
func (m *Middleware) Middleware() func(http.Handler) http.Handler
Middleware implements ports.Middleware by producing the handler adapter.
type Options ¶
type Options struct {
// TrustIncoming strictly validates client-provided traceparent and uses it
// if valid. When false, the middleware always generates a fresh trace ID.
TrustIncoming bool
// SampledFlag defaults to 00 (not sampled). Set to 01 to enable sampling bit.
SampledFlag byte
// TraceIDGen overrides the trace id generator.
TraceIDGen ports.IDGen
// SpanIDGen overrides the span id generator.
SpanIDGen ports.IDGen
}
Options controls middleware behaviour.
Source Files