otlp: refactor config API and deprecate legacy handler

This commit improves the OTLP handler API and prepares for v6 by
deprecating the legacy alpha handler implementation.

Breaking Changes:
- Rename SDKConfig.Endpoint to EndpointURL to clarify it requires
  a full URL with scheme (http:// or https://)
- Use WithEndpointURL instead of WithEndpoint to avoid known gRPC bug
  when using http:// scheme
- Remove enforced defaults for ExportInterval and ExportTimeout,
  allowing SDK to use its own defaults (60s and 30s respectively)

Deprecations:
- Deprecate otlp.Handler (Alpha since 2022, minimal usage)
- Deprecate otlp.HTTPClient
- Deprecate otlp.NewHTTPClient()
All will be removed in v6.0.0. Migration path provided in deprecation
notices with code examples.

Improvements:
- Add Example_fullyConfiguredByEnvironment showing empty SDKConfig usage
- Enhance IMPLEMENTATION_NOTES.md with user-focused temporality explanation
- Clarify instrument caching is internal implementation detail
- Update all examples and tests to use EndpointURL with proper scheme
- Add blank lines around markdown lists to fix linting warnings

Documentation:
- Update HISTORY.md with comprehensive v5.9.0 release notes
- Document breaking changes and migration path
- Add notes about exponential histograms and temporality configuration
- Update all code examples throughout documentation

All tests pass. No functional changes to SDKHandler behavior.

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

Author: etiennep

HISTORY.md

@@ -1,10 +1,10 @@
 # History
 
-### v5.9.0 (February 6, 2026)
+### v5.9.0 (February 19, 2026)
 
 Add full OpenTelemetry OTLP exporter support with official SDK integration.
 
-**New Feature: OpenTelemetry OTLP Exporter**
+**New Feature: OpenTelemetry OTLP Exporter (SDKHandler)**
 
 The `otlp` package now includes a production-ready `SDKHandler` that uses the
 official OpenTelemetry SDK with comprehensive support for modern observability
@@ -17,6 +17,10 @@ requirements:
 - **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
+- **Exponential Histograms**: Optional support for exponential histogram aggregation
+  with configurable bucket size and scale
+- **Temporality Configuration**: Configurable metric temporality (cumulative or delta)
+  with cumulative as the default for Prometheus compatibility
 - **Tag Preservation**: Automatic conversion of stats tags to OpenTelemetry attributes
 - **Production Ready**: Thread-safe instrument caching, proper context handling,
   and comprehensive error handling
@@ -40,19 +44,33 @@ stats.Register(handler)
 
 // Or with explicit configuration
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
-    Protocol: otlp.ProtocolGRPC,
-    Endpoint: "localhost:4317",
+    Protocol:    otlp.ProtocolGRPC,
+    EndpointURL: "http://localhost:4317",
 })
 ```
 
 **Implementation Details:**
 
-- Gauges use `UpDownCounter` with delta calculation to maintain absolute value
-  semantics (workaround until stable OTel SDK adds Gauge instrument)
+- Gauges use native `Float64Gauge` instrument for instantaneous value recording
 - Background context for metric recording to prevent context cancellation issues
-- Lock-free reads for instrument lookup in the hot path
+- Efficient two-level locking pattern for instrument caching (read locks in hot path)
+- Cumulative temporality by default (Prometheus-compatible)
 - Comprehensive documentation including cloud resource detector examples
 
+**Breaking Changes:**
+
+- Config field renamed: `Endpoint` → `EndpointURL` (must include `http://` or `https://` scheme)
+- SDK defaults are now used instead of hardcoded values (ExportInterval: 60s, ExportTimeout: 30s)
+
+**Deprecated:**
+
+- `otlp.Handler` is now deprecated in favor of `otlp.SDKHandler` (will be removed in v6.0.0)
+- `otlp.HTTPClient` is now deprecated in favor of `otlp.SDKHandler` with `ProtocolHTTPProtobuf` (will be removed in v6.0.0)
+- `otlp.NewHTTPClient()` is now deprecated (will be removed in v6.0.0)
+
+The legacy `Handler` has been marked as Alpha since 2022 and has minimal to zero usage.
+Migration is straightforward - see deprecation notices in code for examples.
+
 See the [otlp package documentation](./otlp/README.md) for complete details and examples.
 
 ### v5.8.0 (December 15, 2025)

otlp/IMPLEMENTATION_NOTES.md

@@ -46,17 +46,19 @@ gauge.Record(ctx, 42.0, opts)
 
 ### 3. Instrument Caching
 
-**Implementation**: Thread-safe two-level locking pattern
+**Note**: This is an internal implementation detail - users don't need to worry about this.
+
+**Implementation**: Thread-safe two-level locking pattern for efficient instrument reuse
 ```go
-// Fast path: read lock for lookup
+// Fast path: read lock for lookup (common case - instrument already exists)
 h.mu.RLock()
 inst, exists := h.instruments[metricName]
 h.mu.RUnlock()
 
-// Slow path: write lock only if creating new instrument
+// Slow path: write lock only if creating new instrument (rare - first time seeing this metric)
 if !exists {
     h.mu.Lock()
-    // Double-check after acquiring write lock
+    // Double-check after acquiring write lock (another goroutine may have created it)
     inst, exists = h.instruments[metricName]
     if !exists {
         inst = h.createInstruments(meter, metricName, field.Type())
@@ -66,7 +68,13 @@ if !exists {
 }
 ```
 
-**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.
+**Why**: OpenTelemetry instruments are expensive to create but cheap to reuse. This pattern:
+
+- **Minimizes lock contention** in the hot path (metric recording uses fast read locks)
+- **Ensures thread-safety** during instrument creation (write locks only when needed)
+- **Scales well** under concurrent load (multiple goroutines can look up instruments simultaneously)
+
+The double-check pattern prevents duplicate instrument creation when multiple goroutines race to create the same instrument for the first time.
 
 ### 4. Attribute Handling
 
@@ -227,38 +235,90 @@ if config.ExponentialHistogram {
 
 ## Temporality Configuration
 
-### Default: Cumulative Temporality
+### What is Temporality?
 
-**Decision**: Use cumulative temporality for all metric instruments (Prometheus-compatible)
+Temporality determines whether metrics are reported as **cumulative totals** (since application start) or **deltas** (change since last export).
 
-**Implementation**: OTLP exporters use `DefaultTemporalitySelector` by default
-```go
-// If no TemporalitySelector is provided, the exporter uses:
-// DefaultTemporalitySelector -> CumulativeTemporality for all instruments
-```
+**Example - Request Counter**:
+- **Cumulative**: Export "1000 total requests" → "1150 total requests" → "1320 total requests"
+- **Delta**: Export "1000 new requests" → "150 new requests" → "170 new requests"
 
-**Why**:
-- **Prometheus compatibility**: Prometheus expects cumulative counters
-- **Standard practice**: Most OTLP backends expect cumulative semantics
-- **Query simplicity**: Easier to query and understand (total since start)
-- **No data loss**: Cumulative data can be converted to delta, but not vice versa
+### Why We Use Cumulative Temporality (Default)
+
+This handler uses **cumulative temporality** for all metrics by default. Here's why:
+
+#### Compatibility with Prometheus and Standard Backends
+
+- Prometheus expects cumulative counters and will graph them correctly
+- Most OTLP backends (Grafana, Datadog, etc.) work best with cumulative data
+- Industry standard practice in the OpenTelemetry ecosystem
+
+#### Reliability and Query Simplicity
+
+- **No data loss on export failures**: If an export fails, the next one still has complete data
+- **Easier to query**: "How many total requests?" vs "Sum all deltas"
+- **Converts to delta easily**: Backend can calculate rates from cumulative, but can't reconstruct cumulative from deltas
+
+#### Lower Cognitive Load
+
+- Counters show totals since start - intuitive and matches mental model
+- Histograms show full distribution of all observations
+
+### How It Works
+
+**Cumulative semantics by instrument type**:
 
-**Cumulative semantics by instrument**:
-- **Counter**: Total count since application start (e.g., total requests)
-- **Histogram**: Cumulative distribution of all observed values
-- **UpDownCounter/Gauge**: Current absolute value (naturally stateful)
+- **Counter** (`stats.Incr`, `stats.Add`): Total count since application start
+  - Example: `requests.total` reports 1000, then 1150, then 1320
+
+- **Histogram** (`stats.Observe`): Cumulative distribution of all observed values
+  - Example: Latency histogram includes all requests since start
+
+- **Gauge** (`stats.Set`): Current absolute value (temporality doesn't apply)
+  - Example: `memory.used` always reports current memory usage
+
+### Trade-offs
+
+#### Advantages of Cumulative
+
+- ✅ Prometheus and Grafana work out-of-box
+- ✅ Resilient to export failures (no data loss)
+- ✅ Backend can derive rates automatically
+- ✅ Simpler mental model for most users
+
+#### Disadvantages of Cumulative
+
+- ❌ Slightly higher memory usage for high-cardinality counters
+- ❌ Backend must calculate deltas for rate queries (minor overhead)
+- ❌ Some specialized telemetry systems expect delta temporality
+
+#### When Delta Might Be Better
+
+- Your backend explicitly requires delta temporality (check docs)
+- Extreme cardinality where cumulative memory overhead matters
+- Building a custom metrics pipeline optimized for deltas
+
+### Changing Temporality (Advanced)
+
+If you need delta temporality, you can override the default:
 
-**User override**: Advanced users can specify custom temporality via `TemporalitySelector`:
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
+    Protocol: otlp.ProtocolGRPC,
+    EndpointURL: "http://localhost:4317",
+    // Use delta temporality for all instruments
     TemporalitySelector: sdkmetric.DeltaTemporalitySelector,
 })
 ```
 
-**Trade-offs**:
-- **Memory**: Cumulative uses slightly more memory than delta for high-cardinality counters
-- **Backend requirements**: Some specialized backends prefer delta temporality
-- **Migration**: Changing temporality requires coordinated backend configuration changes
+**Available selectors**:
+
+- `sdkmetric.DefaultTemporalitySelector` - Cumulative for all (default, recommended)
+- `sdkmetric.CumulativeTemporalitySelector` - Cumulative for all (explicit)
+- `sdkmetric.DeltaTemporalitySelector` - Delta for all
+- `sdkmetric.LowMemoryTemporalitySelector` - Delta for Counters/Histograms, Cumulative for UpDownCounters
+
+**⚠️ Warning**: Changing temporality requires updating your backend configuration and queries. Most users should stick with the default cumulative temporality.
 
 ## Future Enhancements
 

otlp/README.md

@@ -38,7 +38,7 @@ func main() {
     // Create handler with gRPC transport
     handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
         Protocol: otlp.ProtocolGRPC,
-        Endpoint: "localhost:4317",
+        EndpointURL: "http://localhost:4317",
     })
     if err != nil {
         log.Fatal(err)
@@ -59,7 +59,7 @@ func main() {
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolHTTPProtobuf,
-    Endpoint: "http://localhost:4318",
+    EndpointURL: "http://localhost:4318",
 })
 ```
 
@@ -83,7 +83,7 @@ type SDKConfig struct {
     // Protocol: "grpc" or "http/protobuf" (default: "grpc")
     Protocol Protocol
 
-    // Endpoint: OTLP collector endpoint
+    // EndpointURL: Full OTLP collector endpoint URL (with http:// or https:// scheme)
     // gRPC: "localhost:4317"
     // HTTP: "http://localhost:4318"
     Endpoint string
@@ -150,7 +150,7 @@ import (
 
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolGRPC,
-    Endpoint: "collector.example.com:4317",
+    EndpointURL: "http://collector.example.com:4317",
     GRPCOptions: []otlpmetricgrpc.Option{
         // Use TLS
         otlpmetricgrpc.WithTLSCredentials(
@@ -173,7 +173,7 @@ import "go.opentelemetry.io/otel/exporters/otlp/otlpmetric/otlpmetrichttp"
 
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolHTTPProtobuf,
-    Endpoint: "https://collector.example.com:4318",
+    EndpointURL: "https://collector.example.com:4318",
     HTTPOptions: []otlpmetrichttp.Option{
         // Add custom headers
         otlpmetrichttp.WithHeaders(map[string]string{
@@ -209,7 +209,7 @@ res, err := resource.New(ctx,
 
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolGRPC,
-    Endpoint: "localhost:4317",
+    EndpointURL: "http://localhost:4317",
     Resource: res,
 })
 ```
@@ -377,7 +377,7 @@ res, err := resource.New(ctx,
 
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolGRPC,
-    Endpoint: "localhost:4317",
+    EndpointURL: "http://localhost:4317",
     Resource: res,
 })
 ```
@@ -428,7 +428,7 @@ func main() {
     // Create handler with detected resources
     handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
         Protocol: otlp.ProtocolGRPC,
-        Endpoint: "collector.us-west-2.amazonaws.com:4317",
+        EndpointURL: "http://collector.us-west-2.amazonaws.com:4317",
         Resource: res,
     })
     if err != nil {
@@ -452,13 +452,13 @@ Send metrics to multiple destinations:
 // Send to local collector
 localHandler, _ := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolGRPC,
-    Endpoint: "localhost:4317",
+    EndpointURL: "http://localhost:4317",
 })
 
 // Send to cloud service
 cloudHandler, _ := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolHTTPProtobuf,
-    Endpoint: "https://api.example.com/v1/metrics",
+    EndpointURL: "https://api.example.com/v1/metrics",
     HTTPOptions: []otlpmetrichttp.Option{
         otlpmetrichttp.WithHeaders(map[string]string{
             "Authorization": "Bearer " + apiKey,
@@ -545,7 +545,7 @@ By default, histograms use explicit bucket aggregation with fixed bucket boundar
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol:             otlp.ProtocolGRPC,
-    Endpoint:             "localhost:4317",
+    EndpointURL:          "http://localhost:4317",
     ExponentialHistogram: true,  // Enable exponential histograms
 })
 ```
@@ -561,7 +561,7 @@ handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol:                      otlp.ProtocolGRPC,
-    Endpoint:                      "localhost:4317",
+    EndpointURL:                   "http://localhost:4317",
     ExponentialHistogram:          true,
     ExponentialHistogramMaxSize:   160,  // Max buckets (default: 160)
     ExponentialHistogramMaxScale:  20,   // Max resolution (default: 20)
@@ -596,7 +596,7 @@ For advanced use cases, you can configure custom temporality:
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol: otlp.ProtocolGRPC,
-    Endpoint: "localhost:4317",
+    EndpointURL: "http://localhost:4317",
     TemporalitySelector: sdkmetric.DeltaTemporalitySelector, // Use delta for all metrics
 })
 ```
@@ -624,7 +624,7 @@ The handler uses **native OpenTelemetry SDK batching** via `PeriodicReader`:
 ```go
 handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
     Protocol:       otlp.ProtocolGRPC,
-    Endpoint:       "localhost:4317",
+    EndpointURL:    "http://localhost:4317",
     ExportInterval: 5 * time.Second,  // Export every 5 seconds
     ExportTimeout:  15 * time.Second, // 15 second timeout per export
 })

otlp/client.go

@@ -12,10 +12,28 @@ import (
 	"google.golang.org/protobuf/proto"
 )
 
+// Deprecated: Client is deprecated and will be removed in v6.
+// It is only used by the deprecated Handler. Use SDKHandler instead.
 type Client interface {
 	Handle(context.Context, *colmetricpb.ExportMetricsServiceRequest) error
 }
 
+// Deprecated: HTTPClient is deprecated and will be removed in v6.
+// Use SDKHandler with ProtocolHTTPProtobuf instead, which provides the official
+// OpenTelemetry SDK with retry logic, proper timeout handling, and full OTLP support.
+//
+// Migration example:
+//
+//	// Old (deprecated)
+//	client := otlp.NewHTTPClient("http://localhost:4318/v1/metrics")
+//	handler := &otlp.Handler{Client: client}
+//
+//	// New (recommended)
+//	handler, err := otlp.NewSDKHandler(ctx, otlp.SDKConfig{
+//	    Protocol: otlp.ProtocolHTTPProtobuf,
+//	    EndpointURL: "http://localhost:4318",
+//	})
+//
 // HTTPClient implements the Client interface and is used to export metrics to
 // an OpenTelemetry Collector through the HTTP interface.
 //
@@ -26,6 +44,8 @@ type HTTPClient struct {
 	endpoint string
 }
 
+// Deprecated: NewHTTPClient is deprecated. Use SDKHandler with ProtocolHTTPProtobuf instead.
+// See HTTPClient documentation for migration example.
 func NewHTTPClient(endpoint string) *HTTPClient {
 	return &HTTPClient{
 		// TODO: add sane default timeout configuration.