tracing

Tracing

A distributed tracing package for Go applications using OpenTelemetry. This package provides easy-to-use tracing functionality with support for various exporters and seamless integration with HTTP frameworks.

📚 Full documentation available at rivaas.dev/docs

Documentation

• Installation - Get started with the tracing package
• User Guide - Learn tracing fundamentals and best practices
• API Reference - Complete API documentation
• Examples - Real-world usage patterns
• Troubleshooting - Common issues and solutions

Features

• OpenTelemetry Integration - Full OpenTelemetry tracing support
• Context Propagation - Automatic trace context propagation across services
• Multiple Providers - Stdout, OTLP (gRPC and HTTP), and Noop exporters
• HTTP Middleware - Standalone middleware for any HTTP framework
• Span Management - Easy span creation and management with lifecycle hooks
• Path Filtering - Exclude specific paths from tracing via middleware options
• Consistent API - Same design patterns as the metrics package

Installation

go get rivaas.dev/tracing

Requires Go 1.25+

Quick Start

package main

import (
    "context"
    "log"
    "net/http"
    
    "rivaas.dev/tracing"
)

func main() {
    // Create tracer
    tracer := tracing.MustNew(
        tracing.WithServiceName("my-service"),
        tracing.WithServiceVersion("v1.0.0"),
        tracing.WithOTLP("localhost:4317"),
    )
    
    // Start tracer (required for OTLP)
    if err := tracer.Start(context.Background()); err != nil {
        log.Fatal(err)
    }
    defer tracer.Shutdown(context.Background())

    // Create HTTP handler
    mux := http.NewServeMux()
    mux.HandleFunc("/api/users", func(w http.ResponseWriter, r *http.Request) {
        w.Write([]byte("Hello"))
    })

    // Wrap with tracing middleware
    handler := tracing.MustMiddleware(tracer,
        tracing.WithExcludePaths("/health", "/metrics"),
    )(mux)

    log.Fatal(http.ListenAndServe(":8080", handler))
}

When using the app package, enable tracing with app.WithObservability(app.WithTracing(...)). Use c.SetSpanAttribute, c.AddSpanEvent, and c.StartSpan / c.FinishSpan for child spans; use c.Tracer() only for advanced use (e.g. passing the tracer to another library).

Learn More

• Installation Guide - Get started
• Basic Usage - Learn the fundamentals
• Providers - Choose the right exporter
• Middleware - HTTP integration
• Context Propagation - Distributed tracing
• Examples - Production-ready configurations

Contributing

Contributions are welcome! Please see the main repository for contribution guidelines.

License

Apache License 2.0 - see LICENSE for details.

---

Part of the Rivaas web framework ecosystem.