docs: update for native stats/opentelemetry migration

FAQ.md

@@ -65,11 +65,12 @@ See the [Tracing How-To](/howto/Tracing/#trace-id-propagation) for details.
 
 ## How do I migrate from OpenTracing to OpenTelemetry?
 
-The `tracing` package supports both. To switch:
+The OpenTracing bridge has been removed. ColdBrew now uses OpenTelemetry natively:
 
-1. Update your tracing initialization to use OpenTelemetry's SDK
-2. The `tracing.NewInternalSpan()`, `tracing.NewDatastoreSpan()`, and `tracing.NewExternalSpan()` functions work with both backends
-3. See the [Tracing How-To](/howto/Tracing/) and [Integrations](/integrations) guides for setup details
+1. Remove any direct `opentracing.GlobalTracer()` calls — use `otel.Tracer("my-service")` instead
+2. The `tracing.NewInternalSpan()`, `tracing.NewDatastoreSpan()`, and `tracing.NewExternalSpan()` functions use OpenTelemetry natively
+3. If you had `OTLP_USE_OPENTRACING_BRIDGE=true`, remove it — the setting is now ignored (a warning is logged if set to `true`)
+4. See the [Tracing How-To](/howto/Tracing/) and [Integrations](/integrations) guides for setup details
 
 ## What is vtprotobuf and why does ColdBrew use it?
 

config-reference.md

@@ -115,7 +115,10 @@ When `OTLP_ENDPOINT` is set, it takes precedence over New Relic OpenTelemetry co
 | `OTLP_COMPRESSION` | string | `gzip` | Compression type: `gzip` or `none` |
 | `OTLP_INSECURE` | bool | `false` | Disable TLS for OTLP connection (development only) |
 | `OTLP_SAMPLING_RATIO` | float64 | `0.1` | Trace sampling ratio (0.0–1.0, where 1.0 = sample all) |
-| `OTLP_USE_OPENTRACING_BRIDGE` | bool | `false` | **Deprecated.** Enable legacy OpenTracing bridge — only needed for services with unmigrated OpenTracing instrumentation |
+| `OTLP_USE_OPENTRACING_BRIDGE` | bool | `false` | **Deprecated.** Ignored — OpenTracing bridge has been removed. If set to `true`, a warning is logged at startup |
+| `OTEL_USE_LEGACY_INSTRUMENTATION` | bool | `false` | Revert to legacy `otelgrpc`-based gRPC OpenTelemetry instrumentation. Set to `true` only for rollback |
+| `ENABLE_OTEL_METRICS` | bool | `false` | Enable OpenTelemetry metrics export via OTLP alongside Prometheus. Does not replace Prometheus |
+| `OTEL_METRICS_INTERVAL` | int | `60` | Export interval in seconds for OTEL metrics (only applies when `ENABLE_OTEL_METRICS=true`) |
 
 ## Error Tracking
 
@@ -150,7 +153,7 @@ When `OTLP_ENDPOINT` is set, it takes precedence over New Relic OpenTelemetry co
 |----------|------------|-------|
 | `HTTP_HEADER_PREFIX` | `HTTP_HEADER_PREFIXES` | Single prefix replaced by comma-separated list |
 | `DISABLE_PORMETHEUS` | `DISABLE_PROMETHEUS` | Typo variant — both work, use the correct spelling |
-| `OTLP_USE_OPENTRACING_BRIDGE` | Remove | Legacy OpenTracing bridge — remove once all instrumentation uses OpenTelemetry |
+| `OTLP_USE_OPENTRACING_BRIDGE` | Remove | OpenTracing bridge has been removed — this field is now ignored (logs a warning if set to `true`) |
 
 ---
 

howto/Debugging.md

@@ -65,7 +65,7 @@ Here's what a typical ColdBrew CPU profile looks like under load (Apple M1 Pro,
 | Go runtime (scheduling, GC) | ~15% | Goroutine scheduling, garbage collection |
 | `TraceIdInterceptor` | ~6% | Trace ID extraction and propagation |
 | `errors/notifier.SetTraceIdWithValue` | ~5% | Setting trace ID on error notifier context |
-| `otelgrpc.TagRPC` | ~1% | OpenTelemetry span creation |
+| gRPC OpenTelemetry stats handler | ~1% | OpenTelemetry span creation |
 | Prometheus metrics | ~1% | Histogram bucket recording |
 
 {: .important }
@@ -79,7 +79,7 @@ curl -s "http://localhost:9091/debug/pprof/heap?debug=0" -o heap.prof
 go tool pprof -alloc_objects -top heap.prof
 ```
 
-Top allocation sources under load are gRPC metadata copying (~27%), otelgrpc span creation (~13%), and options context store (~10%). These are largely inherent to gRPC's per-request metadata model.
+Top allocation sources under load are gRPC metadata copying (~27%), OpenTelemetry span creation (~13%), and options context store (~10%). These are largely inherent to gRPC's per-request metadata model.
 
 ### Analyzing profiles
 

integrations.md

@@ -156,14 +156,13 @@ To configure generic OpenTelemetry, you can use the [OTLPConfig] struct:
 
 ```go
 type OTLPConfig struct {
-    Endpoint             string            // OTLP gRPC endpoint (e.g., "localhost:4317")
-    Headers              map[string]string // Custom headers (e.g., API keys)
-    ServiceName          string            // Name of your service
-    ServiceVersion       string            // Version of your service
-    SamplingRatio        float64           // Sampling ratio (0.0 to 1.0)
-    Compression          string            // "gzip" or "none"
-    UseOpenTracingBridge bool              // Deprecated: enable legacy OpenTracing bridge
-    Insecure             bool              // Disable TLS (for local development)
+    Endpoint       string            // OTLP gRPC endpoint (e.g., "localhost:4317")
+    Headers        map[string]string // Custom headers (e.g., API keys)
+    ServiceName    string            // Name of your service
+    ServiceVersion string            // Version of your service
+    SamplingRatio  float64           // Sampling ratio (0.0 to 1.0)
+    Compression    string            // "gzip" or "none"
+    Insecure       bool              // Disable TLS (for local development)
 }
 ```
 
@@ -174,12 +173,11 @@ import "github.com/go-coldbrew/core"
 
 func main() {
     config := core.OTLPConfig{
-        Endpoint:             "localhost:4317",
-        ServiceName:          "my-service",
-        ServiceVersion:       "v1.0.0",
-        SamplingRatio:        0.1,
-        // UseOpenTracingBridge: true, // only needed for legacy OpenTracing code
-        Insecure:             true,  // for local development
+        Endpoint:       "localhost:4317",
+        ServiceName:    "my-service",
+        ServiceVersion: "v1.0.0",
+        SamplingRatio:  0.1,
+        Insecure:       true, // for local development
     }
     err := core.SetupOpenTelemetry(config)
     if err != nil {
@@ -201,12 +199,11 @@ import "github.com/go-coldbrew/core"
 
 func main() {
     config := core.OTLPConfig{
-        Endpoint:             "localhost:4317",  // Jaeger OTLP endpoint
-        ServiceName:          "my-service",
-        ServiceVersion:       "v1.0.0",
-        SamplingRatio:        0.1,
-        // UseOpenTracingBridge: true, // only needed for legacy OpenTracing code
-        Insecure:             true,
+        Endpoint:       "localhost:4317", // Jaeger OTLP endpoint
+        ServiceName:    "my-service",
+        ServiceVersion: "v1.0.0",
+        SamplingRatio:  0.1,
+        Insecure:       true,
     }
     err := core.SetupOpenTelemetry(config)
     if err != nil {