Metrics Package

Package Information

• Import Path: rivaas.dev/metrics
• Go Version: 1.25+
• Documentation: pkg.go.dev/rivaas.dev/metrics
• Source Code: GitHub

Package Overview

The metrics package provides OpenTelemetry-based metrics collection for Go applications with support for multiple exporters including Prometheus, OTLP, and stdout.

Core Features

• Multiple metrics providers (Prometheus, OTLP, stdout)
• Built-in HTTP metrics via middleware
• Custom metrics (counters, histograms, gauges)
• Thread-safe operations
• Context-aware methods
• Automatic header filtering for security
• Testing utilities

Architecture

The package is built on OpenTelemetry and provides a simplified interface for common metrics use cases.

graph TD
    App[Application Code]
    Recorder[Recorder]
    Provider[Provider Layer]
    Prom[Prometheus]
    OTLP[OTLP]
    Stdout[Stdout]
    Middleware[HTTP Middleware]
    
    App -->|Record Metrics| Recorder
    Middleware -->|Auto-Collect| Recorder
    Recorder --> Provider
    Provider --> Prom
    Provider --> OTLP
    Provider --> Stdout

Components

Main Package (rivaas.dev/metrics)

Core metrics collection including:

• Recorder - Main metrics recorder
• New() / MustNew() - Recorder initialization
• Custom metrics methods - Counters, histograms, gauges
• Middleware() - HTTP metrics collection
• Testing utilities

Quick API Index

Recorder Creation

recorder, err := metrics.New(options...)     // With error handling
recorder := metrics.MustNew(options...)      // Panics on error

Lifecycle Management

err := recorder.Start(ctx context.Context)   // Start metrics server/exporter
err := recorder.Shutdown(ctx context.Context) // Graceful shutdown
err := recorder.ForceFlush(ctx context.Context) // Force immediate export

Recording Metrics

// Counters
err := recorder.IncrementCounter(ctx, name, attributes...)
err := recorder.AddCounter(ctx, name, value, attributes...)

// Histograms
err := recorder.RecordHistogram(ctx, name, value, attributes...)

// Gauges
err := recorder.SetGauge(ctx, name, value, attributes...)

HTTP Middleware

handler := metrics.Middleware(recorder, options...)(httpHandler)

Provider-Specific Methods

address := recorder.ServerAddress()          // Prometheus: actual address
handler, err := recorder.Handler()           // Prometheus: metrics handler
count := recorder.CustomMetricCount()        // Number of custom metrics

Testing Utilities

recorder := metrics.TestingRecorder(t, serviceName)
recorder := metrics.TestingRecorderWithPrometheus(t, serviceName)
err := metrics.WaitForMetricsServer(t, address, timeout)

Reference Pages

Type Reference

Recorder

type Recorder struct {
    // contains filtered or unexported fields
}

Main metrics recorder. Thread-safe for concurrent access.

Methods: See API Reference for complete method documentation.

Option

type Option func(*Recorder)

Configuration option function type used with New() and MustNew().

Available Options: See Options for all options.

EventType

type EventType int

const (
    EventError   EventType = iota // Error events
    EventWarning                   // Warning events
    EventInfo                      // Informational events
    EventDebug                     // Debug events
)

Event severity levels for internal operational events.

Event

type Event struct {
    Type    EventType
    Message string
    Args    []any // slog-style key-value pairs
}

Internal operational event from the metrics package.

EventHandler

type EventHandler func(Event)

Processes internal operational events. Used with WithEventHandler option.

Common Patterns

Basic Usage

recorder := metrics.MustNew(
    metrics.WithPrometheus(":9090", "/metrics"),
    metrics.WithServiceName("my-api"),
)
recorder.Start(context.Background())
defer recorder.Shutdown(context.Background())

_ = recorder.IncrementCounter(ctx, "requests_total")

With HTTP Middleware

recorder := metrics.MustNew(
    metrics.WithPrometheus(":9090", "/metrics"),
    metrics.WithServiceName("my-api"),
)
recorder.Start(context.Background())

handler := metrics.Middleware(recorder,
    metrics.WithExcludePaths("/health"),
)(httpHandler)

http.ListenAndServe(":8080", handler)

With OTLP

recorder := metrics.MustNew(
    metrics.WithOTLP("http://localhost:4318"),
    metrics.WithServiceName("my-service"),
)
recorder.Start(ctx) // Required before recording metrics
defer recorder.Shutdown(context.Background())

Thread Safety

The Recorder type is thread-safe for:

• All metric recording methods
• Concurrent Start() and Shutdown() operations
• Mixed recording and lifecycle operations

Not thread-safe for:

• Concurrent modification during initialization

Performance Notes

• Metric recording: ~1-2 microseconds per operation
• HTTP middleware: ~1-2 microseconds overhead per request
• Memory usage: Scales with number of unique metric names and label combinations
• Histogram overhead: Proportional to bucket count

Best Practices:

• Use fire-and-forget pattern for most metrics (ignore errors)
• Limit metric cardinality (avoid high-cardinality labels)
• Customize histogram buckets for your use case
• Exclude high-traffic paths from middleware when appropriate

Built-in Metrics

When using HTTP middleware, these metrics are automatically collected:

Version Compatibility

The metrics package follows semantic versioning. The API is stable for the v1 series.

Minimum Go version: 1.25

OpenTelemetry compatibility: Uses OpenTelemetry SDK v1.x

Next Steps

• Read the API Reference for detailed method documentation
• Explore Options for all available configuration options
• Check Middleware Options for HTTP integration
• Review Troubleshooting for common issues

For learning-focused guides, see the Metrics Guide.