Add W3C Trace Context propagation via MCP _meta (#3682)

* Add W3C Trace Context propagation via MCP _meta

Add MetaCarrier (TextMapCarrier for MCP _meta fields) and
InjectMetaTraceContext for injecting traceparent/tracestate
into outgoing MCP requests, per the MCP OTEL specification.

This enables distributed tracing across vMCP → backend boundaries
using the standard W3C Trace Context format propagated through
MCP params._meta.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* Address review comments for trace context propagation

- Add compile-time assertion that MetaCarrier implements propagation.TextMapCarrier
- Refactor TestMetaCarrier_GetSetKeys to use table-driven test pattern for Get operations

Co-authored-by: Jakub Hrozek <jhrozek@users.noreply.github.com>

* Fix lint: Add t.Parallel() to table-driven test subtests

- Added t.Parallel() call in subtests to satisfy paralleltest/tparallel linters
- Maintains test isolation while allowing parallel execution

Co-authored-by: Chris Burns <ChrisJBurns@users.noreply.github.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: claude[bot] <41898282+claude[bot]@users.noreply.github.com>
Co-authored-by: Jakub Hrozek <jhrozek@users.noreply.github.com>
Co-authored-by: Chris Burns <ChrisJBurns@users.noreply.github.com>

Author: 4 people

pkg/telemetry/propagation.go

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package telemetry
+
+import (
+	"context"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+)
+
+// Compile-time assertion that MetaCarrier implements propagation.TextMapCarrier
+var _ propagation.TextMapCarrier = (*MetaCarrier)(nil)
+
+// MetaCarrier implements propagation.TextMapCarrier for MCP _meta fields.
+// This enables W3C Trace Context propagation through MCP request params._meta,
+// as recommended by the MCP OpenTelemetry specification.
+//
+// The carrier wraps a map[string]interface{} (the _meta field from MCP params)
+// and allows the OpenTelemetry propagator to inject/extract traceparent and
+// tracestate headers into/from the map.
+type MetaCarrier struct {
+	meta map[string]interface{}
+}
+
+// NewMetaCarrier creates a new MetaCarrier wrapping the given meta map.
+// If meta is nil, a new empty map is created.
+func NewMetaCarrier(meta map[string]interface{}) *MetaCarrier {
+	if meta == nil {
+		meta = make(map[string]interface{})
+	}
+	return &MetaCarrier{meta: meta}
+}
+
+// Get returns the value associated with the passed key.
+func (c *MetaCarrier) Get(key string) string {
+	if v, ok := c.meta[key]; ok {
+		if s, ok := v.(string); ok {
+			return s
+		}
+	}
+	return ""
+}
+
+// Set stores the key-value pair.
+func (c *MetaCarrier) Set(key string, value string) {
+	c.meta[key] = value
+}
+
+// Keys lists the keys stored in this carrier.
+func (c *MetaCarrier) Keys() []string {
+	keys := make([]string, 0, len(c.meta))
+	for k := range c.meta {
+		keys = append(keys, k)
+	}
+	return keys
+}
+
+// Meta returns the underlying meta map. Use this after injection to retrieve
+// the enriched map containing trace context fields.
+func (c *MetaCarrier) Meta() map[string]interface{} {
+	return c.meta
+}
+
+// InjectMetaTraceContext injects the current trace context from ctx directly into
+// the given meta map using W3C Trace Context format (traceparent, tracestate).
+//
+// This function operates directly on the meta map contents. Use this when you
+// already have the _meta map and want to inject trace context fields into it.
+func InjectMetaTraceContext(ctx context.Context, meta map[string]interface{}) {
+	if meta == nil {
+		return
+	}
+	carrier := NewMetaCarrier(meta)
+	otel.GetTextMapPropagator().Inject(ctx, carrier)
+}

pkg/telemetry/propagation_test.go

@@ -0,0 +1,154 @@
+// SPDX-FileCopyrightText: Copyright 2025 Stacklok, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+package telemetry
+
+import (
+	"context"
+	"testing"
+
+	"go.opentelemetry.io/otel"
+	"go.opentelemetry.io/otel/propagation"
+	sdktrace "go.opentelemetry.io/otel/sdk/trace"
+)
+
+func TestMetaCarrier_GetSetKeys(t *testing.T) {
+	t.Parallel()
+
+	meta := map[string]interface{}{
+		"existing": "value",
+		"number":   42,
+	}
+	carrier := NewMetaCarrier(meta)
+
+	// Table-driven test for Get operations
+	getTests := []struct {
+		name string
+		key  string
+		want string
+	}{
+		{
+			name: "existing string value",
+			key:  "existing",
+			want: "value",
+		},
+		{
+			name: "non-string value returns empty",
+			key:  "number",
+			want: "",
+		},
+		{
+			name: "non-existent key returns empty",
+			key:  "missing",
+			want: "",
+		},
+	}
+
+	for _, tt := range getTests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+			if got := carrier.Get(tt.key); got != tt.want {
+				t.Errorf("Get(%q) = %q, want %q", tt.key, got, tt.want)
+			}
+		})
+	}
+
+	// Test Set
+	carrier.Set("traceparent", "00-abc123-def456-01")
+	if got := carrier.Get("traceparent"); got != "00-abc123-def456-01" {
+		t.Errorf("Get(traceparent) after Set = %q, want %q", got, "00-abc123-def456-01")
+	}
+
+	// Verify set also updates underlying map
+	if v, ok := meta["traceparent"]; !ok || v != "00-abc123-def456-01" {
+		t.Errorf("underlying map not updated: got %v", v)
+	}
+
+	// Test Keys
+	keys := carrier.Keys()
+	if len(keys) != 3 { // existing, number, traceparent
+		t.Errorf("Keys() returned %d keys, want 3", len(keys))
+	}
+	keyMap := make(map[string]bool)
+	for _, k := range keys {
+		keyMap[k] = true
+	}
+	for _, expected := range []string{"existing", "number", "traceparent"} {
+		if !keyMap[expected] {
+			t.Errorf("Keys() missing key %q", expected)
+		}
+	}
+}
+
+func TestNewMetaCarrier_NilMeta(t *testing.T) {
+	t.Parallel()
+
+	carrier := NewMetaCarrier(nil)
+	if carrier.meta == nil {
+		t.Error("NewMetaCarrier(nil) should create a non-nil map")
+	}
+
+	carrier.Set("key", "value")
+	if got := carrier.Get("key"); got != "value" {
+		t.Errorf("Get(key) = %q, want %q", got, "value")
+	}
+}
+
+func TestMetaCarrier_Meta(t *testing.T) {
+	t.Parallel()
+
+	original := map[string]interface{}{"foo": "bar"}
+	carrier := NewMetaCarrier(original)
+
+	returned := carrier.Meta()
+	if returned["foo"] != "bar" {
+		t.Error("Meta() should return the underlying map")
+	}
+
+	// Verify it's the same map (not a copy)
+	carrier.Set("new", "val")
+	if returned["new"] != "val" {
+		t.Error("Meta() should return the same map reference")
+	}
+}
+
+// Tests below mutate the global OTEL propagator, so they must NOT use t.Parallel().
+
+func TestInjectMetaTraceContext(t *testing.T) { //nolint:paralleltest // Mutates global OTEL propagator
+	oldPropagator := otel.GetTextMapPropagator()
+	otel.SetTextMapPropagator(propagation.TraceContext{})
+	defer otel.SetTextMapPropagator(oldPropagator)
+
+	tp := sdktrace.NewTracerProvider()
+	defer func() { _ = tp.Shutdown(context.Background()) }()
+	tracer := tp.Tracer("test")
+	ctx, span := tracer.Start(context.Background(), "test-span")
+	defer span.End()
+
+	// InjectMetaTraceContext injects directly into the meta map
+	meta := map[string]interface{}{
+		"progressToken": "tok-456",
+	}
+	InjectMetaTraceContext(ctx, meta)
+
+	// traceparent should be added directly as a key in the meta map
+	traceparent, ok := meta["traceparent"]
+	if !ok {
+		t.Fatal("traceparent not found in meta after InjectMetaTraceContext")
+	}
+	if tp1, ok := traceparent.(string); !ok || tp1 == "" {
+		t.Errorf("traceparent = %v, want non-empty string", traceparent)
+	}
+
+	// Existing fields should be preserved
+	if meta["progressToken"] != "tok-456" {
+		t.Error("existing progressToken was overwritten by InjectMetaTraceContext")
+	}
+}
+
+func TestInjectMetaTraceContext_NilMeta(t *testing.T) {
+	t.Parallel()
+
+	// Should not panic
+	InjectMetaTraceContext(context.Background(), nil)
+}