🐹 Go Fan Report: OpenTelemetry Go SDK

Module Overview

go.opentelemetry.io/otel is the official OpenTelemetry SDK for Go — distributed tracing, context propagation, OTLP export, and semantic conventions. The project uses it at v1.43.0 (latest stable) across four sub-modules: core API, SDK, trace, and OTLP/HTTP exporter.

Current Usage in gh-aw-mcpg

The gateway has a well-structured tracing layer under internal/tracing/ with good noop/live toggle and W3C propagation support.

• Files: 5 files (tracing/provider.go, tracing/http.go, server/unified.go, server/http_helpers.go, proxy/handler.go)
• Key APIs Used: sdktrace.NewTracerProvider, otlptracehttp.New, noop.NewTracerProvider, span.RecordError, span.SetStatus, resource.New, propagation.NewCompositeTextMapPropagator
• Sampler logic: AlwaysSample / NeverSample / TraceIDRatioBased based on config
• Semantic conventions: semconv/v1.26.0 used across all files

Research Findings

Recent Updates (v1.43.0)

• v1.43.0 is the current stable release — the project is fully up-to-date
• semconv v1.27.0 is available within the same module (project uses v1.26.0)
• No breaking changes between 1.26.0 and 1.27.0 semconv — safe upgrade

Best Practices

• Always use a ResponseWriter wrapper to capture HTTP response status and set it on the span
• Set codes.Error on spans returning 5xx responses; set semconv.HTTPResponseStatusCodeKey
• Use span.AddEvent for lifecycle milestones (not just errors)
• Avoid putting raw err.Error() in SetStatus description — OTel backends may log these publicly; prefer fixed messages and use RecordError(err) for the full error

Improvement Opportunities

🏃 Quick Wins

1. WrapHTTPHandler missing HTTP response status recording

tracing/http.go WrapHTTPHandler wraps next.ServeHTTP(w, r.WithContext(ctx)) but never captures the response status code. Per OTel HTTP semantic conventions, http.response.status_code SHOULD be set, and spans with 4xx/5xx should have codes.Error set.

// Add a responseWriter wrapper:
type statusResponseWriter struct {
    http.ResponseWriter
    statusCode int
}
func (rw *statusResponseWriter) WriteHeader(code int) {
    rw.statusCode = code
    rw.ResponseWriter.WriteHeader(code)
}

// In WrapHTTPHandler, after next.ServeHTTP:
srw := &statusResponseWriter{ResponseWriter: w, statusCode: http.StatusOK}
next.ServeHTTP(srw, r.WithContext(ctx))
span.SetAttributes(semconv.HTTPResponseStatusCodeKey.Int(srw.statusCode))
if srw.statusCode >= 500 {
    span.SetStatus(codes.Error, http.StatusText(srw.statusCode))
}

2. Bump semconv from v1.26.0 → v1.27.0

The module ships both. v1.27.0 adds network.* attributes and clarifies http.* naming. A one-line import change in 4 files.

✨ Feature Opportunities

3. Propagate session.id in W3C Baggage

The W3C Baggage propagator is already registered but never written to. Injecting session.id into baggage would allow downstream services (e.g., OTLP collectors, backend MCP servers) to correlate requests without needing OTel instrumentation themselves.

ctx = baggage.ContextWithBaggage(ctx, /* baggage with session.id */)

4. Span events for lifecycle milestones

span.AddEvent("tools/list.resolved", oteltrace.WithAttributes(...)) would enrich traces without adding new spans. Good candidates: session creation, tool list resolution, circuit breaker state changes.

5. mTLS support for OTLP export

The gateway supports mTLS for inbound connections. For consistency, otlptracehttp.WithTLSClientConfig could be exposed via config for OTLP endpoints requiring mutual TLS.

📐 Best Practice Alignment

6. Raw error in SetStatus description

unified.go:556: execSpan.SetStatus(codes.Error, err.Error()) puts the raw error string in the span status description. This can leak internal details to trace backends. Prefer:

execSpan.RecordError(err)  // already called on line 555
execSpan.SetStatus(codes.Error, "tool execution failed")  // fixed message

7. Missing codes.Ok for explicit success

OTel recommends setting codes.Ok on spans that represent explicitly successful operations (e.g., after a tool call completes with a valid response). Currently the status is left as Unset on success.

🔧 General Improvements

8. resource.WithHost() in provider

Already used ✅. But resource.WithOSDescription() and resource.WithContainerID() (via resource.WithDetectors) could enrich the resource for containerized deployments — the gateway explicitly supports Docker.

Recommendations

Next Steps

• Add statusResponseWriter wrapper to tracing/http.go
• Replace execSpan.SetStatus(codes.Error, err.Error()) with fixed message
• Update semconv import to v1.27.0

Generated by Go Fan 🐹
Module summary saved to: specs/mods/opentelemetry-otel.md
Run: §25153854887

tools:
  github:
    min-integrity: approved  # merged | approved | unapproved | none

Generated by Go Fan · ● 1.8M · ◷

• expires on May 7, 2026, 7:57 AM UTC