Add OpenTelemetry OTLP exporter with full SDK

Implement production-ready OpenTelemetry Protocol (OTLP) exporter using
the official OpenTelemetry SDK with support for both gRPC and HTTP
transports.

Features:
- gRPC and HTTP/Protobuf protocol support
- Full OTEL_* environment variable integration
- Automatic resource detection (AWS, GCP, Azure, K8s)
- Counter, Gauge, and Histogram metric types
- Tag to attribute conversion
- Thread-safe instrument caching
- Proper gauge semantics via delta calculation

Implementation:
- Uses UpDownCounter for gauges with delta tracking to maintain
  absolute value semantics (workaround until stable SDK adds Gauge)
- Background context for recording to avoid cancellation issues
- Lock-free reads for instrument lookup in hot path
- Comprehensive tests and benchmarks

Documentation:
- Complete README with configuration examples
- Cloud resource detector usage guides
- Implementation notes explaining design decisions
- Example code for common use cases

Bumps version to 5.9.0

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: etiennep

HISTORY.md

@@ -1,5 +1,60 @@
 # History
 
+### v5.9.0 (February 6, 2026)
+
+Add full OpenTelemetry OTLP exporter support with official SDK integration.
+
+**New Feature: OpenTelemetry OTLP Exporter**
+
+The `otlp` package now includes a production-ready `SDKHandler` that uses the
+official OpenTelemetry SDK with comprehensive support for modern observability
+requirements:
+
+- **Dual Transport Support**: Both gRPC and HTTP/Protobuf protocols
+- **Environment Variables**: Full support for all standard `OTEL_*` environment
+  variables including `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_PROTOCOL`,
+  `OTEL_RESOURCE_ATTRIBUTES`, etc.
+- **Automatic Resource Detection**: Built-in support for AWS (EC2, ECS, EKS, Lambda),
+  GCP (Compute Engine), Azure (VM), Kubernetes, host, and process metadata
+- **All Metric Types**: Counter, Gauge, and Histogram with proper semantics
+- **Tag Preservation**: Automatic conversion of stats tags to OpenTelemetry attributes
+- **Production Ready**: Thread-safe instrument caching, proper context handling,
+  and comprehensive error handling
+
+**Usage Example:**
+
+```go
+import (
+    "context"
+    "github.com/segmentio/stats/v5"
+    "github.com/segmentio/stats/v5/otlp"
+)
+
+// Simple usage with environment variables
+handler, err := otlp.NewSDKHandlerFromEnv(ctx)
+if err != nil {
+    log.Fatal(err)
+}
+defer handler.Shutdown(ctx)
+stats.Register(handler)
+
+// Or with explicit configuration
+handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
+    Protocol: otlp.ProtocolGRPC,
+    Endpoint: "localhost:4317",
+})
+```
+
+**Implementation Details:**
+
+- Gauges use `UpDownCounter` with delta calculation to maintain absolute value
+  semantics (workaround until stable OTel SDK adds Gauge instrument)
+- Background context for metric recording to prevent context cancellation issues
+- Lock-free reads for instrument lookup in the hot path
+- Comprehensive documentation including cloud resource detector examples
+
+See the [otlp package documentation](./otlp/README.md) for complete details and examples.
+
 ### v5.8.0 (December 15, 2025)
 
 When reporting go/stats versions, ensure that any user provided tags are

README.md

@@ -121,6 +121,88 @@ func main() {
 }
 ```
 
+## Supported Backends
+
+The stats package supports multiple metric backends out of the box:
+
+### OpenTelemetry (OTLP)
+
+The [github.com/segmentio/stats/v5/otlp](https://pkg.go.dev/github.com/segmentio/stats/v5/otlp) package provides full OpenTelemetry Protocol (OTLP) support using the official OpenTelemetry SDK.
+
+**Features:**
+
+- gRPC and HTTP/Protobuf transports
+- Full support for OTEL_* environment variables
+- Automatic resource detection (cloud, Kubernetes, host, process)
+- Production-ready with official OTel SDK exporters
+
+```go
+import (
+    "context"
+    "github.com/segmentio/stats/v5"
+    "github.com/segmentio/stats/v5/otlp"
+)
+
+func main() {
+    ctx := context.Background()
+
+    // Using gRPC (recommended)
+    handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
+        Protocol: otlp.ProtocolGRPC,
+        Endpoint: "localhost:4317",
+    })
+    if err != nil {
+        panic(err)
+    }
+    defer handler.Shutdown(ctx)
+
+    stats.Register(handler)
+    defer stats.Flush()
+
+    // Or use environment variables (simplest)
+    // export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+    // export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
+    handler, err = otlp.NewSDKHandlerFromEnv(ctx)
+}
+```
+
+See the [otlp package documentation](./otlp/README.md) for complete details.
+
+### Datadog
+
+The [github.com/segmentio/stats/v5/datadog](https://godoc.org/github.com/segmentio/stats/v5/datadog) package provides support for sending metrics to Datadog via DogStatsD protocol over UDP or Unix Domain Sockets.
+
+```go
+import "github.com/segmentio/stats/v5/datadog"
+
+stats.Register(datadog.NewClient("localhost:8125"))
+```
+
+### Prometheus
+
+The [github.com/segmentio/stats/v5/prometheus](https://godoc.org/github.com/segmentio/stats/v5/prometheus) package exposes an HTTP handler that serves metrics in Prometheus format.
+
+```go
+import (
+    "net/http"
+    "github.com/segmentio/stats/v5/prometheus"
+)
+
+handler := prometheus.NewHandler()
+stats.Register(handler)
+http.Handle("/metrics", handler)
+```
+
+### InfluxDB
+
+The [github.com/segmentio/stats/v5/influxdb](https://godoc.org/github.com/segmentio/stats/v5/influxdb) package sends metrics to InfluxDB using the line protocol over HTTP.
+
+```go
+import "github.com/segmentio/stats/v5/influxdb"
+
+stats.Register(influxdb.NewClient("http://localhost:8086"))
+```
+
 ### Metrics
 
 - [Gauges](https://godoc.org/github.com/segmentio/stats#Gauge)

otlp/IMPLEMENTATION_NOTES.md

@@ -0,0 +1,245 @@
+# OpenTelemetry SDK Implementation Notes
+
+This document describes the implementation details and design decisions for the OpenTelemetry OTLP exporter.
+
+## Overview
+
+This implementation provides full OpenTelemetry Protocol (OTLP) support using the official OpenTelemetry SDK. It bridges the `stats` library's metric interface to OpenTelemetry's metric API.
+
+## Architecture
+
+### Core Components
+
+1. **SDKHandler** - Main handler implementing `stats.Handler`
+2. **Protocol Support** - Both gRPC and HTTP/Protobuf transports
+3. **Instrument Management** - Efficient caching of OpenTelemetry instruments
+4. **Gauge Value Tracking** - Delta calculation for absolute gauge semantics
+
+## Design Decisions
+
+### 1. Gauge Implementation
+
+**Challenge**: OpenTelemetry's stable SDK doesn't have a true Gauge instrument yet.
+
+**Solution**: Use `Float64UpDownCounter` with delta calculation to maintain absolute value semantics.
+
+```go
+// When stats.Set("metric", 42) is called:
+// 1. Calculate delta: newValue - previousValue
+// 2. Call UpDownCounter.Add(delta)
+// 3. Store newValue for next delta calculation
+```
+
+**Why**: Users expect `stats.Set("metric", 42)` to set the metric to 42, not add 42 to the previous value. By tracking previous values and calculating deltas, we maintain this semantic while using UpDownCounter.
+
+**Trade-off**: Requires additional memory to track gauge values per metric+attribute combination.
+
+### 2. Context Management
+
+**Challenge**: Stored contexts can be cancelled, causing metric recording to fail.
+
+**Solution**:
+- Use `context.Background()` for metric recording operations
+- Store the initialization context as `shutdownCtx` only for shutdown operations
+- This ensures metrics continue to be recorded even if the original context is cancelled
+
+**Why**: Metric recording should be resilient and not fail due to context cancellation. The handler should continue working throughout the application lifecycle.
+
+### 3. Instrument Caching
+
+**Implementation**: Thread-safe two-level locking pattern
+```go
+// Fast path: read lock for lookup
+h.mu.RLock()
+inst, exists := h.instruments[metricName]
+h.mu.RUnlock()
+
+// Slow path: write lock only if creating new instrument
+if !exists {
+    h.mu.Lock()
+    // Double-check after acquiring write lock
+    inst, exists = h.instruments[metricName]
+    if !exists {
+        inst = h.createInstruments(meter, metricName, field.Type())
+        h.instruments[metricName] = inst
+    }
+    h.mu.Unlock()
+}
+```
+
+**Why**: Instruments are created once per metric name and reused. This pattern minimizes lock contention in the hot path (metric recording) while ensuring thread-safety during instrument creation.
+
+### 4. Attribute Handling
+
+**Implementation**: Direct conversion from `stats.Tag` to `attribute.KeyValue`
+```go
+func (h *SDKHandler) tagsToAttributes(tags []stats.Tag) []attribute.KeyValue {
+    attrs := make([]attribute.KeyValue, 0, len(tags))
+    for _, tag := range tags {
+        attrs = append(attrs, attribute.String(tag.Name, tag.Value))
+    }
+    return attrs
+}
+```
+
+**Why**: Simple 1:1 mapping preserves all user-provided metadata without transformation.
+
+### 5. Resource Detection
+
+**Pattern**: Leverage official OpenTelemetry resource detectors
+```go
+resource.New(ctx,
+    resource.WithDetectors(ec2.NewResourceDetector()),
+    resource.WithFromEnv(),
+    resource.WithHost(),
+    resource.WithProcess(),
+)
+```
+
+**Why**: Automatic detection of cloud provider, Kubernetes, host, and process metadata without manual configuration.
+
+## Performance Considerations
+
+### Instrument Reuse
+- Instruments are created once and cached
+- RWMutex allows concurrent reads (the common case)
+- Write locks only taken during initial instrument creation
+
+### Gauge Delta Calculation
+- Memory overhead: O(unique metric × unique attribute sets)
+- Computational overhead: One map lookup + one subtraction per gauge recording
+- Trade-off: Necessary to maintain correct gauge semantics
+
+### Batching and Export Strategy
+
+**Decision**: Delegate all batching to OpenTelemetry SDK's `PeriodicReader`
+
+**Implementation**: No custom buffering or batching logic in the handler
+```go
+provider := sdkmetric.NewMeterProvider(
+    sdkmetric.WithResource(res),
+    sdkmetric.WithReader(sdkmetric.NewPeriodicReader(exporter,
+        sdkmetric.WithInterval(config.ExportInterval),  // Default: 10s
+        sdkmetric.WithTimeout(config.ExportTimeout),    // Default: 30s
+    )),
+)
+```
+
+**Why**:
+- The OTel SDK provides production-ready batching with in-memory aggregation
+- `PeriodicReader` handles timing, aggregation reset, and export lifecycle
+- Avoids reinventing batching logic and potential bugs
+- Provides standard OTel behavior that users expect
+
+**How it works**:
+1. Metrics are recorded immediately to OTel instruments (no blocking)
+2. SDK aggregates metrics in memory (e.g., summing counters, collecting histogram samples)
+3. Every `ExportInterval`, the reader exports aggregated data and resets aggregations
+4. Reduces network overhead and collector load automatically
+
+**Trade-offs**:
+- Metrics are not real-time (delayed by up to `ExportInterval`)
+- Memory grows proportionally to metric cardinality until export
+- Users must call `Flush()` before shutdown to export remaining metrics
+
+## Error Handling
+
+### Instrument Creation Failures
+- Logged but don't block other metrics
+- Silent no-op if instrument is nil
+- Prevents cascade failures
+
+### Export Failures
+- Logged but don't stop metric collection
+- Retries handled by OpenTelemetry SDK exporters
+- Backoff and timeout configured at SDK level
+
+### Context Cancellation
+- Metric recording uses background context
+- Unaffected by user context cancellation
+- Shutdown still respects user-provided context
+
+## Testing Strategy
+
+### Unit Tests
+- Instrument creation and caching
+- Gauge delta calculation
+- Value type conversions
+- Protocol selection (HTTP vs gRPC)
+
+### Integration Tests
+- Environment variable configuration
+- Multiple concurrent metrics
+- Gauge absolute value semantics
+
+### Benchmarks
+- Metric recording performance
+- Lock contention under load
+
+## Limitations and Known Issues
+
+### 1. Gauge Implementation
+- Requires tracking previous values in memory
+- High cardinality can increase memory usage
+- Memory is never freed (instruments are cached forever)
+
+### 2. No Exemplars
+- Current implementation doesn't support exemplars
+- Could be added in future versions
+
+### 3. No Custom Views
+- Uses default aggregation and views
+- Advanced users may want custom histogram buckets or aggregations
+
+## Future Enhancements
+
+### Potential Improvements
+1. **Memory Management**: Add LRU eviction for unused instruments
+2. **Exemplar Support**: Bridge to trace context for exemplars
+3. **Custom Views**: Allow users to configure aggregations
+4. **Metric Metadata**: Expose units and descriptions via OTel API
+5. **Delta vs Cumulative**: Support both temporality modes
+
+### OpenTelemetry SDK Evolution
+- **Gauge Support**: When stable SDK adds Gauge, migrate from UpDownCounter
+- **New Instrument Types**: Support ExponentialHistogram when available
+- **Protocol Extensions**: Support new OTLP features as they're added
+
+## Migration from Legacy Handler
+
+The legacy `Handler` in this package is marked as Alpha and has limitations:
+
+**Legacy Handler Issues:**
+- Custom OTLP implementation (not using official SDK)
+- Only HTTP transport (despite having gRPC dependencies)
+- No environment variable support
+- No resource detection
+
+**SDKHandler Advantages:**
+- Official OpenTelemetry SDK
+- Both HTTP and gRPC
+- Full environment variable support
+- Automatic resource detection
+- Production-ready and well-tested
+
+**Migration Path:**
+```go
+// Old (legacy)
+handler := &otlp.Handler{
+    Client: otlp.NewHTTPClient(endpoint),
+    // ...
+}
+
+// New (recommended)
+handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
+    Protocol: otlp.ProtocolHTTPProtobuf,
+    Endpoint: endpoint,
+})
+```
+
+## References
+
+- [OpenTelemetry Metrics Specification](https://opentelemetry.io/docs/specs/otel/metrics/)
+- [OTLP Specification](https://opentelemetry.io/docs/specs/otlp/)
+- [Go SDK Documentation](https://pkg.go.dev/go.opentelemetry.io/otel/sdk/metric)
+- [Resource Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/resource/)