diff --git a/architecture.md b/architecture.md index e1b123f..1e5577f 100644 --- a/architecture.md +++ b/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 diff --git a/config-reference.md b/config-reference.md index 3101725..fa21f30 100644 --- a/config-reference.md +++ b/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 diff --git a/howto/Tracing.md b/howto/Tracing.md index 1104ed6..d564d3e 100644 --- a/howto/Tracing.md +++ b/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. diff --git a/integrations.md b/integrations.md index 5e2fd8e..102b216 100644 --- a/integrations.md +++ b/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)