observability

README

OpenTelemetry Observability Package

This package provides a unified OpenTelemetry tracing implementation for all zen components.

Features

• ✅ Consolidated OTEL initialization
• ✅ Configurable sampling rates
• ✅ HTTP middleware for automatic request tracing
• ✅ Proper shutdown handling
• ✅ Environment variable configuration
• ✅ Support for OTLP HTTP exporter
• ✅ W3C TraceContext propagation

Usage

Basic Initialization

import (
    "context"
    "github.com/kube-zen/zen-sdk/pkg/observability"
)

func main() {
    ctx := context.Background()
    
    // Initialize with defaults (uses environment variables)
    shutdown, err := observability.InitWithDefaults(ctx, "my-service")
    if err != nil {
        log.Fatal(err)
    }
    defer shutdown(ctx)
    
    // ... rest of application
}

Custom Configuration

config := observability.Config{
    ServiceName:      "zen-back",
    ServiceVersion:   "1.0.0",
    Environment:      "production",
    SamplingRate:     0.1, // 10% sampling
    OTLPEndpoint:     "http://otel-collector:4318",
    Insecure:         false, // Use TLS in production
}

shutdown, err := observability.Init(ctx, config)
if err != nil {
    log.Fatal(err)
}
defer shutdown(ctx)

HTTP Middleware

import (
    "net/http"
    "github.com/kube-zen/zen-sdk/pkg/observability"
)

func setupRoutes() {
    mux := http.NewServeMux()
    
    // Add tracing middleware (wraps handler with automatic span creation)
    // Parameters: tracerName, route
    handler := observability.HTTPTracingMiddleware("zen-back/http", "/api/users")(myHandler)
    mux.Handle("/api/users", handler)
    
    // For multiple routes, create middleware for each route
    usersHandler := observability.HTTPTracingMiddleware("zen-back/http", "/api/users")(handleUsers)
    ordersHandler := observability.HTTPTracingMiddleware("zen-back/http", "/api/orders")(handleOrders)
    mux.Handle("/api/users", usersHandler)
    mux.Handle("/api/orders", ordersHandler)
}

Manual Span Creation

import (
    "github.com/kube-zen/zen-sdk/pkg/observability"
)

func myFunction(ctx context.Context) {
    tracer := observability.GetTracer("my-package")
    ctx, span := tracer.Start(ctx, "my-operation")
    defer span.End()
    
    // ... do work
}

Environment Variables

• OTEL_SERVICE_NAME - Service name (overrides provided serviceName)
• OTEL_EXPORTER_TYPE - Exporter type: "otlp", "otlphttp", "stdout" (default: "otlphttp")
• OTEL_EXPORTER_OTLP_ENDPOINT - OTLP endpoint URL (default: service-specific)
• OTEL_COLLECTOR_ENDPOINT - Legacy endpoint variable (fallback)
• DEPLOYMENT_ENV - Deployment environment (e.g., "production", "staging")
• VERSION - Service version (or OTEL_SERVICE_VERSION)

Configuration Best Practices

1. Sampling Rate: Use 10% (0.1) for high-volume services, 100% (1.0) for low-volume critical services
2. Security: Set Insecure: false in production, use TLS
3. Service Name: Use consistent naming: zen-{component} (e.g., zen-back, zen-bff)
4. Shutdown: Always call the shutdown function during graceful shutdown

Integration with zen-sdk/pkg/logging

This package works seamlessly with zen-sdk/pkg/logging. Trace IDs and Span IDs are automatically extracted from context by the logging package:

import (
    "github.com/kube-zen/zen-sdk/pkg/logging"
    "github.com/kube-zen/zen-sdk/pkg/observability"
)

func handler(ctx context.Context) {
    // Create span
    tracer := observability.GetTracer("my-component")
    ctx, span := tracer.Start(ctx, "my-operation")
    defer span.End()
    
    // Log with automatic trace context extraction
    logger := logging.NewLogger("my-component")
    logger.WithContext(ctx).Info("Operation started")
    // Trace ID and Span ID are automatically added to logs
}

Documentation

Index

• func GetTracer(name string) trace.Tracer
• func HTTPTracingMiddleware(tracerName, route string) func(http.Handler) http.Handler
• func Init(ctx context.Context, config Config) (func(context.Context) error, error)
• func InitWithDefaults(ctx context.Context, serviceName string) (func(context.Context) error, error)
• func Shutdown(ctx context.Context) error
• type Config
  • func DefaultConfig(serviceName string) Config

Functions

func GetTracer

func GetTracer(name string) trace.Tracer

GetTracer returns a tracer for the given name. The name is typically the package or component name (e.g., "zen-back/http"). This tracer can be used to create spans for distributed tracing.

func HTTPTracingMiddleware

func HTTPTracingMiddleware(tracerName, route string) func(http.Handler) http.Handler

HTTPTracingMiddleware creates HTTP middleware that adds tracing to HTTP requests. It extracts trace context from headers, creates a span for the request, and adds span attributes for HTTP method, route, URL, status code, and duration.

func Init

func Init(ctx context.Context, config Config) (func(context.Context) error, error)

Init initializes OpenTelemetry tracing for the application. This sets up the global tracer provider and configures trace context propagation.

The exporter type can be specified in config or via OTEL_EXPORTER_TYPE environment variable:

• "otlp" or "otlphttp": Uses OTLP HTTP exporter
• "stdout" or empty: Tracing disabled (no-op)

Returns a shutdown function that should be called during application shutdown, and an error if initialization fails.

func InitWithDefaults

func InitWithDefaults(ctx context.Context, serviceName string) (func(context.Context) error, error)

InitWithDefaults initializes OpenTelemetry with default configuration. Uses environment variables for configuration:

• OTEL_SERVICE_NAME (required, or use provided serviceName)
• OTEL_EXPORTER_TYPE (optional, defaults to "otlphttp")
• OTEL_EXPORTER_OTLP_ENDPOINT (optional, defaults to service-specific endpoint)
• DEPLOYMENT_ENV (optional, for environment tag)

func Shutdown

func Shutdown(ctx context.Context) error

Shutdown gracefully shuts down the tracer provider. This flushes any pending spans and closes connections to the exporter. Should be called during application shutdown to ensure all traces are exported.

Types

type Config

type Config struct {
	ServiceName    string  // Service name (required)
	ServiceVersion string  // Service version (optional, defaults to "dev")
	Environment    string  // Deployment environment (optional)
	SamplingRate   float64 // Sampling rate (0.0-1.0, default: 0.1 = 10%)
	OTLPEndpoint   string  // OTLP endpoint (optional, uses env var or default)
	ExporterType   string  // Exporter type: "otlp", "otlphttp", "stdout" (optional, uses env var)
	Insecure       bool    // Use insecure connection for OTLP (default: true for development)
}

Config holds OpenTelemetry configuration

func DefaultConfig

func DefaultConfig(serviceName string) Config

DefaultConfig returns a config with sensible defaults