Trace

Documentation Index

Fetch the complete documentation index at: https://docs.go-mizu.dev/llms.txt

Use this file to discover all available pages before exploring further.

​

Overview

• Distributed tracing
• Request correlation
• Service observability

​

Installation

import "github.com/go-mizu/mizu/middlewares/trace"

​

Quick Start

app := mizu.New()

app.Use(trace.New())

app.Get("/api", func(c *mizu.Ctx) error {
    traceID := trace.ID(c)
    log.Printf("Trace: %s", traceID)
    return c.JSON(200, data)
})

​

Configuration

​

Options

​

Examples

​

Basic Tracing

app.Use(trace.New())

​

W3C Trace Context

app.Use(trace.W3C())
// Uses traceparent header

​

Custom Headers

app.Use(trace.WithOptions(trace.Options{
    TraceHeader:  "X-Request-ID",
    SpanHeader:   "X-Span-ID",
    ParentHeader: "X-Parent-Span-ID",
}))

​

Access Trace Info

app.Get("/", func(c *mizu.Ctx) error {
    traceID := trace.ID(c)
    spanID := trace.SpanID(c)
    parentID := trace.ParentID(c)

    // Include in logs
    log.Printf("[%s] Request processed", traceID)

    return c.JSON(200, data)
})

​

Propagate to Downstream

app.Get("/", func(c *mizu.Ctx) error {
    // Create HTTP client with trace context
    req, _ := http.NewRequest("GET", "http://service-b/api", nil)
    trace.Inject(c, req.Header)

    resp, _ := http.DefaultClient.Do(req)
    // ...
})

​

API Reference

​

Functions

// New creates trace middleware
func New() mizu.Middleware

// W3C creates W3C trace context middleware
func W3C() mizu.Middleware

// WithOptions creates with configuration
func WithOptions(opts Options) mizu.Middleware

// Context access
func ID(c *mizu.Ctx) string
func SpanID(c *mizu.Ctx) string
func ParentID(c *mizu.Ctx) string

// Propagation
func Inject(c *mizu.Ctx, headers http.Header)

​

Technical Details

​

Implementation Architecture

1. Context Propagation: Uses Go’s context.Context to store span information throughout the request lifecycle
2. Span Generation: Creates unique trace and span IDs using cryptographic randomness (16 bytes encoded as hex)
3. Header-based Propagation: Extracts and injects trace context via HTTP headers for cross-service communication

​

Core Components

• TraceID: Unique identifier for the entire trace across services
• SpanID: Unique identifier for this specific operation
• ParentID: Reference to the parent span for hierarchy
• StartTime/EndTime: Timing information for duration calculation
• Status: Enumerated status (Unset, OK, Error)
• Tags: Key-value metadata for context
• Events: Timestamped events within the span

1. Extract or generate trace ID from request headers
2. Create new span with generated span ID
3. Store span in request context
4. Set response headers for downstream propagation
5. Execute handler chain
6. Calculate duration and set final status
7. Invoke OnSpan callback if configured

• Thread-safe span collection
• In-memory storage
• Clear method for test isolation

​

Configuration Defaults

​

Best Practices

• Use consistent format across services
• Include trace ID in all logs
• Propagate to all downstream calls
• Consider W3C standard for interoperability

​

Testing

​

Related Middlewares

• requestid - Request IDs
• otel - OpenTelemetry
• logger - Request logging