docs: update for OTEL migration — remove OpenTracing references

architecture.md

@@ -154,11 +154,11 @@ When a request arrives at a ColdBrew service, it flows through several layers:
   │  │                                           │   │
   │  │  1. Response Time Logging                 │   │
   │  │  2. Trace ID Injection                    │   │
-  │  │  3. OpenTracing / OpenTelemetry           │   │
-  │  │  4. Prometheus Metrics                    │   │
-  │  │  5. Error Notification (Sentry/Rollbar)   │   │
-  │  │  6. New Relic Transaction                 │   │
-  │  │  7. Panic Recovery                        │   │
+  │  │  3. Prometheus Metrics                    │   │
+  │  │  4. Error Notification (Sentry/Rollbar)   │   │
+  │  │  5. New Relic Transaction                 │   │
+  │  │  6. Panic Recovery                        │   │
+  │  │  (OTEL tracing via gRPC stats handler)    │   │
   │  │                                           │   │
   │  └────────────────────┬─────────────────────┘   │
   │                       │                          │
@@ -200,11 +200,13 @@ Interceptors are gRPC middleware that run on every request. ColdBrew chains them
 |-------|------------|---------|--------------|
 | 1 | Response Time Logging | `interceptors` | Logs method name, duration, and status code |
 | 2 | Trace ID | `interceptors` | Generates a trace ID (or reads it from the `x-trace-id` HTTP header or a `trace_id` proto field) and propagates it to structured logs and Sentry/Rollbar error reports |
-| 3 | OpenTracing | `grpc_opentracing` | Creates a tracing span for the request |
-| 4 | Prometheus | `interceptors` | Records request count, latency histogram, and status codes |
-| 5 | Error Notification | `interceptors` | Sends errors to Sentry/Rollbar/Airbrake asynchronously |
-| 6 | New Relic | `interceptors` | Creates a New Relic transaction for APM |
-| 7 | Panic Recovery | `interceptors` | Catches panics and converts them to gRPC errors |
+| 3 | Prometheus | `interceptors` | Records request count, latency histogram, and status codes |
+| 4 | Error Notification | `interceptors` | Sends errors to Sentry/Rollbar/Airbrake asynchronously |
+| 5 | New Relic | `interceptors` | Creates a New Relic transaction for APM |
+| 6 | Panic Recovery | `interceptors` | Catches panics and converts them to gRPC errors |
+
+{: .note }
+OpenTelemetry tracing spans are created by the `otelgrpc` stats handler configured at the gRPC server/client level, not as an interceptor in the chain.
 
 {: .note }
 Health checks, ready checks, and gRPC reflection are **excluded by default** via `FilterMethods`. This prevents observability noise from Kubernetes probes. See the [FAQ](/faq) for how to customize this.
@@ -228,10 +230,12 @@ When your service calls other gRPC services, ColdBrew applies client-side interc
 
 | Interceptor | What It Does |
 |------------|--------------|
-| OpenTracing | Propagates trace context to downstream services |
 | Hystrix | Circuit breaking (deprecated — consider failsafe-go) |
 | Retry | Automatic retries with backoff |
 
+{: .note }
+Trace context propagation to downstream services is handled by the `otelgrpc` client stats handler, not a chain interceptor.
+
 ## Context Propagation
 
 ColdBrew uses `context.Context` to propagate metadata through every layer:
@@ -249,7 +253,7 @@ ColdBrew uses `context.Context` to propagate metadata through every layer:
        │
        ├── trace span (distributed tracing)
        │     Create: tracing.NewInternalSpan(ctx, "operation")
-       │     Propagated by: OpenTracing interceptor
+       │     Propagated by: OTEL gRPC stats handler
        │
        └── trace ID (request correlation)
              Injected by: Trace ID interceptor

config-reference.md

@@ -111,7 +111,7 @@ 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.2` | Trace sampling ratio (0.0–1.0, where 1.0 = sample all) |
-| `OTLP_USE_OPENTRACING_BRIDGE` | bool | `true` | Enable OpenTracing compatibility bridge for existing instrumentation |
+| `OTLP_USE_OPENTRACING_BRIDGE` | bool | `false` | **Deprecated.** Enable legacy OpenTracing bridge — only needed for services with unmigrated OpenTracing instrumentation |
 
 ## Error Tracking
 

howto/Tracing.md

@@ -187,7 +187,7 @@ Once extracted, the trace ID is propagated to:
 | **Request context** | Stored in ColdBrew options | Accessible via `notifier.GetTraceId(ctx)` in your handler code |
 
 {: .note }
-ColdBrew's trace ID is separate from OpenTelemetry's W3C trace context. OpenTelemetry spans have their own trace/span IDs managed by the tracing SDK. ColdBrew's trace ID is a lightweight request correlation ID for logs and error reports — it can also read from an existing OpenTracing span's `"trace"` baggage item if one exists.
+ColdBrew's trace ID is separate from OpenTelemetry's W3C trace context. OpenTelemetry spans have their own trace/span IDs managed by the tracing SDK. ColdBrew's trace ID is a lightweight application-level correlation ID for logs and error reports, derived from the incoming header or proto field, or generated randomly when none is provided.
 
 This means a single trace ID connects your logs and error reports — you can search for `req-abc-123` in your log aggregator and Sentry to find the complete request flow.
 

integrations.md

@@ -162,7 +162,7 @@ type OTLPConfig struct {
     ServiceVersion       string            // Version of your service
     SamplingRatio        float64           // Sampling ratio (0.0 to 1.0)
     Compression          string            // "gzip" or "none"
-    UseOpenTracingBridge bool              // Enable OpenTracing compatibility
+    UseOpenTracingBridge bool              // Deprecated: enable legacy OpenTracing bridge
     Insecure             bool              // Disable TLS (for local development)
 }
 ```
@@ -178,7 +178,7 @@ func main() {
         ServiceName:          "my-service",
         ServiceVersion:       "v1.0.0",
         SamplingRatio:        0.1,
-        UseOpenTracingBridge: true,
+        // UseOpenTracingBridge: true, // only needed for legacy OpenTracing code
         Insecure:             true,  // for local development
     }
     err := core.SetupOpenTelemetry(config)
@@ -205,7 +205,7 @@ func main() {
         ServiceName:          "my-service",
         ServiceVersion:       "v1.0.0",
         SamplingRatio:        0.1,
-        UseOpenTracingBridge: true,
+        // UseOpenTracingBridge: true, // only needed for legacy OpenTracing code
         Insecure:             true,
     }
     err := core.SetupOpenTelemetry(config)