OpenTelemetry

​

Overview

• Distributed tracing
• OpenTelemetry integration
• Observability platforms (Jaeger, Zipkin, etc.)

​

Installation

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

​

Quick Start

app := mizu.New()

// Initialize OpenTelemetry
shutdown := otel.Init(otel.Options{
    ServiceName: "my-service",
    Endpoint:    "localhost:4317",
})
defer shutdown()

app.Use(otel.Middleware())

​

Configuration

​

Options

​

Examples

​

Basic Setup

shutdown := otel.Init(otel.Options{
    ServiceName: "api",
    Endpoint:    "localhost:4317",
})
defer shutdown()

app.Use(otel.Middleware())

​

With Jaeger

shutdown := otel.Init(otel.Options{
    ServiceName: "api",
    Endpoint:    "jaeger:4317",
    Propagators: []string{"jaeger", "w3c"},
})

​

Custom Spans

app.Get("/process", func(c *mizu.Ctx) error {
    ctx, span := otel.StartSpan(c, "process-data")
    defer span.End()

    // Add attributes
    span.SetAttributes(
        attribute.String("user.id", userID),
    )

    // Do work
    result := processData(ctx)

    return c.JSON(200, result)
})

​

Propagate to Downstream

app.Get("/", func(c *mizu.Ctx) error {
    req, _ := http.NewRequestWithContext(c.Context(), "GET", url, nil)
    otel.Inject(c.Context(), req.Header)
    // Make request...
})

​

API Reference

​

Functions

// Init initializes OpenTelemetry
func Init(opts Options) func()

// Middleware creates OTel middleware
func Middleware() mizu.Middleware

// StartSpan creates child span
func StartSpan(c *mizu.Ctx, name string) (context.Context, trace.Span)

// Inject propagates context
func Inject(ctx context.Context, headers http.Header)

​

Technical Details

​

Architecture

​

Components

• Name (HTTP method + path)
• Parent/child relationships
• Start/end timestamps
• Status (Unset, OK, Error)
• Attributes (key-value pairs)
• Events (timestamped logs)
• Links (connections to other spans)

• InMemoryProcessor: Stores spans in memory for testing
• PrintProcessor: Prints spans to stdout
• Custom processors can export to external systems

​

Propagation Formats

• Header: Traceparent: 00-{traceId}-{spanId}-{flags}
• Optional: Tracestate for vendor-specific data
• Format: version-traceId-spanId-flags

• Single header: B3: {traceId}-{spanId}-{sampled}
• Multi-header: X-B3-Traceid, X-B3-Spanid, X-B3-Sampled
• Compatible with Zipkin and other B3-based systems

​

ID Generation

• TraceID: 128-bit (16 bytes) cryptographically random hex string
• SpanID: 64-bit (8 bytes) cryptographically random hex string
• Generated using crypto/rand for uniqueness

​

Request Flow

1. Extract parent context from incoming request headers
2. Create new span with inherited TraceID or generate new one
3. Generate new SpanID for current span
4. Add default HTTP attributes (method, URL, status, etc.)
5. Call OnStart hook if configured
6. Inject trace context into response headers
7. Store span in request context
8. Execute handler
9. Set final status and attributes based on response
10. Call OnEnd hook and SpanProcessor

​

Thread Safety

• Span methods use mutex locks for concurrent access
• InMemoryProcessor is thread-safe with mutex protection
• Safe for use with concurrent requests

​

Best Practices

• Use consistent service names
• Add meaningful span attributes
• Propagate context to all calls
• Sample appropriately in production

​

Testing

​

Related Middlewares

• trace - Simple tracing
• prometheus - Prometheus metrics
• sentry - Error tracking