refactor(tracing): rearrange type parameters & avoid nested generic type parameter (#1599)

**Description**

This stops the nested generics type embedding and switches to have
explicit type parameters for generic tracing interfaces.

**Related Issues/PRs (if applicable)**

Follow up on #1582

---------

Signed-off-by: Takeshi Yoneda <[email protected]>

Author: mathetake

internal/extproc/chatcompletion_processor_test.go

@@ -71,7 +71,7 @@ func Test_chatCompletionProcessorUpstreamFilter_SelectTranslator(t *testing.T) {
 }
 
 type mockTracer struct {
-	tracing.NoopTracer[openai.ChatCompletionRequest, tracing.ChatCompletionSpan]
+	tracing.NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]
 	startSpanCalled bool
 	returnedSpan    tracing.ChatCompletionSpan
 }
@@ -88,7 +88,7 @@ func (m *mockTracer) StartSpanAndInjectHeaders(_ context.Context, _ map[string]s
 func Test_chatCompletionProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 	t.Run("body parser error", func(t *testing.T) {
 		p := &chatCompletionProcessorRouterFilter{
-			tracer: tracing.NoopTracer[openai.ChatCompletionRequest, tracing.ChatCompletionSpan]{},
+			tracer: tracing.NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{},
 		}
 		_, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: []byte("nonjson")})
 		require.ErrorContains(t, err, "invalid character 'o' in literal null")
@@ -100,7 +100,7 @@ func Test_chatCompletionProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 			config:         &filterapi.RuntimeConfig{},
 			requestHeaders: headers,
 			logger:         slog.Default(),
-			tracer:         tracing.NoopTracer[openai.ChatCompletionRequest, tracing.ChatCompletionSpan]{},
+			tracer:         tracing.NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{},
 		}
 		resp, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: bodyFromModel(t, "some-model", false, nil)})
 		require.NoError(t, err)
@@ -159,7 +159,7 @@ func Test_chatCompletionProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 				},
 				requestHeaders: headers,
 				logger:         slog.Default(),
-				tracer:         tracing.NoopTracer[openai.ChatCompletionRequest, tracing.ChatCompletionSpan]{},
+				tracer:         tracing.NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{},
 			}
 			resp, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: bodyFromModel(t, "some-model", true, opt)})
 			require.NoError(t, err)

internal/extproc/completions_processor_test.go

@@ -423,7 +423,7 @@ func (m *mockCompletionTranslator) ResponseError(map[string]string, io.Reader) (
 
 // mockCompletionTracer implements tracing.CompletionTracer for testing span creation.
 type mockCompletionTracer struct {
-	tracing.NoopTracer[openai.CompletionRequest, tracing.CompletionSpan]
+	tracing.NoopTracer[openai.CompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponse]
 	startSpanCalled bool
 	returnedSpan    tracing.CompletionSpan
 }

internal/extproc/embeddings_processor_test.go

@@ -59,7 +59,7 @@ func Test_embeddingsProcessorUpstreamFilter_SelectTranslator(t *testing.T) {
 func Test_embeddingsProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 	t.Run("body parser error", func(t *testing.T) {
 		p := &embeddingsProcessorRouterFilter{
-			tracer: tracing.NoopTracer[openai.EmbeddingRequest, tracing.EmbeddingsSpan]{},
+			tracer: tracing.NoopTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]{},
 		}
 		_, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: []byte("nonjson")})
 		require.ErrorContains(t, err, "invalid character 'o' in literal null")
@@ -71,7 +71,7 @@ func Test_embeddingsProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 			config:         &filterapi.RuntimeConfig{},
 			requestHeaders: headers,
 			logger:         slog.Default(),
-			tracer:         tracing.NoopTracer[openai.EmbeddingRequest, tracing.EmbeddingsSpan]{},
+			tracer:         tracing.NoopTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]{},
 		}
 		resp, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: embeddingBodyFromModel(t, "some-model")})
 		require.NoError(t, err)

internal/extproc/imagegeneration_processor_test.go

@@ -60,7 +60,7 @@ func Test_imageGenerationProcessorUpstreamFilter_SelectTranslator(t *testing.T)
 }
 
 type mockImageGenerationTracer struct {
-	tracing.NoopTracer[openaisdk.ImageGenerateParams, tracing.ImageGenerationSpan]
+	tracing.NoopTracer[openaisdk.ImageGenerateParams, openaisdk.ImagesResponse, struct{}]
 	startSpanCalled bool
 	returnedSpan    tracing.ImageGenerationSpan
 }

internal/extproc/rerank_processor_test.go

@@ -54,7 +54,7 @@ func Test_rerankProcessorUpstreamFilter_SelectTranslator(t *testing.T) {
 func Test_rerankProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 	t.Run("body parser error", func(t *testing.T) {
 		p := &rerankProcessorRouterFilter{
-			tracer: tracing.NoopTracer[cohere.RerankV2Request, tracing.RerankSpan]{},
+			tracer: tracing.NoopTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]{},
 		}
 		_, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: []byte("nonjson")})
 		require.ErrorContains(t, err, "invalid character 'o' in literal null")
@@ -66,7 +66,7 @@ func Test_rerankProcessorRouterFilter_ProcessRequestBody(t *testing.T) {
 			config:         &filterapi.RuntimeConfig{},
 			requestHeaders: headers,
 			logger:         slog.Default(),
-			tracer:         tracing.NoopTracer[cohere.RerankV2Request, tracing.RerankSpan]{},
+			tracer:         tracing.NoopTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]{},
 		}
 		resp, err := p.ProcessRequestBody(t.Context(), &extprocv3.HttpBody{Body: rerankBodyFromModel("rerank-english-v3")})
 		require.NoError(t, err)

internal/tracing/api/api.go

@@ -38,7 +38,7 @@ type (
 		Shutdown(context.Context) error
 	}
 	// RequestTracer standardizes tracer implementations for non-MCP requests.
-	RequestTracer[ReqT any, SpanT any] interface {
+	RequestTracer[ReqT any, RespT any, RespChunkT any] interface {
 		// StartSpanAndInjectHeaders starts a span and injects trace context into the header mutation.
 		//
 		// Parameters:
@@ -49,25 +49,25 @@ type (
 		//   - body: contains the original raw request body as a byte slice.
 		//
 		// Returns nil unless the span is sampled.
-		StartSpanAndInjectHeaders(ctx context.Context, headers map[string]string, carrier propagation.TextMapCarrier, req *ReqT, body []byte) SpanT
+		StartSpanAndInjectHeaders(ctx context.Context, headers map[string]string, carrier propagation.TextMapCarrier, req *ReqT, body []byte) Span[RespT, RespChunkT]
 	}
 	// ChatCompletionTracer creates spans for OpenAI chat completion requests.
-	ChatCompletionTracer = RequestTracer[openai.ChatCompletionRequest, ChatCompletionSpan]
+	ChatCompletionTracer = RequestTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]
 	// CompletionTracer creates spans for OpenAI completion requests.
-	CompletionTracer = RequestTracer[openai.CompletionRequest, CompletionSpan]
+	CompletionTracer = RequestTracer[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]
 	// EmbeddingsTracer creates spans for OpenAI embeddings requests.
-	EmbeddingsTracer = RequestTracer[openai.EmbeddingRequest, EmbeddingsSpan]
+	EmbeddingsTracer = RequestTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]
 	// ImageGenerationTracer creates spans for OpenAI image generation requests.
-	ImageGenerationTracer = RequestTracer[openaisdk.ImageGenerateParams, ImageGenerationSpan]
+	ImageGenerationTracer = RequestTracer[openaisdk.ImageGenerateParams, openaisdk.ImagesResponse, struct{}]
 	// RerankTracer creates spans for rerank requests.
-	RerankTracer = RequestTracer[cohere.RerankV2Request, RerankSpan]
+	RerankTracer = RequestTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]
 )
 
 type (
 	// Span standardizes span interfaces, supporting both streaming and non-streaming endpoints.
-	Span[ChunkT any, RespT any] interface {
+	Span[RespT any, RespChunkT any] interface {
 		// RecordResponseChunk records streaming response chunks. Implementations that do not support streaming should provide a no-op implementation.
-		RecordResponseChunk(resp *ChunkT)
+		RecordResponseChunk(resp *RespChunkT)
 		// RecordResponse records the response attributes to the span.
 		RecordResponse(resp *RespT)
 		// EndSpanOnError finalizes and ends the span with an error status.
@@ -76,21 +76,21 @@ type (
 		EndSpan()
 	}
 	// ChatCompletionSpan represents an OpenAI chat completion.
-	ChatCompletionSpan = Span[openai.ChatCompletionResponseChunk, openai.ChatCompletionResponse]
+	ChatCompletionSpan = Span[openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]
 	// CompletionSpan represents an OpenAI completion request.
 	// Note: Completion streaming chunks are full CompletionResponse objects, not deltas like chat completions.
 	CompletionSpan = Span[openai.CompletionResponse, openai.CompletionResponse]
 	// EmbeddingsSpan represents an OpenAI embeddings request. The chunk type is unused and therefore set to struct{}.
-	EmbeddingsSpan = Span[struct{}, openai.EmbeddingResponse]
+	EmbeddingsSpan = Span[openai.EmbeddingResponse, struct{}]
 	// ImageGenerationSpan represents an OpenAI image generation.
-	ImageGenerationSpan = Span[struct{}, openaisdk.ImagesResponse]
+	ImageGenerationSpan = Span[openaisdk.ImagesResponse, struct{}]
 	// RerankSpan represents a rerank request span.
-	RerankSpan = Span[struct{}, cohere.RerankV2Response]
+	RerankSpan = Span[cohere.RerankV2Response, struct{}]
 )
 
 type (
 	// SpanRecorder standardizes recorder implementations for non-MCP tracers.
-	SpanRecorder[ReqT any, ChunkT any, RespT any] interface {
+	SpanRecorder[ReqT any, RespT any, RespChunkT any] interface {
 		// StartParams returns the name and options to start the span with.
 		//
 		// Parameters:
@@ -106,19 +106,19 @@ type (
 		// RecordResponseOnError ends recording the span with an error status.
 		RecordResponseOnError(span trace.Span, statusCode int, body []byte)
 		// RecordResponseChunks records response chunk attributes to the span for streaming response.
-		RecordResponseChunks(span trace.Span, chunks []*ChunkT)
+		RecordResponseChunks(span trace.Span, chunks []*RespChunkT)
 	}
 	// ChatCompletionRecorder records attributes to a span according to a semantic convention.
-	ChatCompletionRecorder = SpanRecorder[openai.ChatCompletionRequest, openai.ChatCompletionResponseChunk, openai.ChatCompletionResponse]
+	ChatCompletionRecorder = SpanRecorder[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]
 	// CompletionRecorder records attributes to a span according to a semantic convention.
 	// Note: Completion streaming chunks are full CompletionResponse objects, not deltas like chat completions.
 	CompletionRecorder = SpanRecorder[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]
 	// ImageGenerationRecorder records attributes to a span according to a semantic convention.
-	ImageGenerationRecorder = SpanRecorder[openaisdk.ImageGenerateParams, struct{}, openaisdk.ImagesResponse]
+	ImageGenerationRecorder = SpanRecorder[openaisdk.ImageGenerateParams, openaisdk.ImagesResponse, struct{}]
 	// EmbeddingsRecorder records attributes to a span according to a semantic convention.
-	EmbeddingsRecorder = SpanRecorder[openai.EmbeddingRequest, struct{}, openai.EmbeddingResponse]
+	EmbeddingsRecorder = SpanRecorder[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]
 	// RerankRecorder records attributes to a span according to a semantic convention.
-	RerankRecorder = SpanRecorder[cohere.RerankV2Request, struct{}, cohere.RerankV2Response]
+	RerankRecorder = SpanRecorder[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]
 )
 
 // NoopChunkRecorder provides a no-op RecordResponseChunks implementation for recorders that don't emit streaming chunks.
@@ -136,27 +136,27 @@ func (t NoopTracing) MCPTracer() MCPTracer {
 
 // ChatCompletionTracer implements Tracing.ChatCompletionTracer.
 func (NoopTracing) ChatCompletionTracer() ChatCompletionTracer {
-	return NoopTracer[openai.ChatCompletionRequest, ChatCompletionSpan]{}
+	return NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{}
 }
 
 // CompletionTracer implements Tracing.CompletionTracer.
 func (NoopTracing) CompletionTracer() CompletionTracer {
-	return NoopTracer[openai.CompletionRequest, CompletionSpan]{}
+	return NoopTracer[openai.CompletionRequest, openai.CompletionResponse, openai.CompletionResponse]{}
 }
 
 // EmbeddingsTracer implements Tracing.EmbeddingsTracer.
 func (NoopTracing) EmbeddingsTracer() EmbeddingsTracer {
-	return NoopTracer[openai.EmbeddingRequest, EmbeddingsSpan]{}
+	return NoopTracer[openai.EmbeddingRequest, openai.EmbeddingResponse, struct{}]{}
 }
 
 // ImageGenerationTracer implements Tracing.ImageGenerationTracer.
 func (NoopTracing) ImageGenerationTracer() ImageGenerationTracer {
-	return NoopTracer[openaisdk.ImageGenerateParams, ImageGenerationSpan]{}
+	return NoopTracer[openaisdk.ImageGenerateParams, openaisdk.ImagesResponse, struct{}]{}
 }
 
 // RerankTracer implements Tracing.RerankTracer.
 func (NoopTracing) RerankTracer() RerankTracer {
-	return NoopTracer[cohere.RerankV2Request, RerankSpan]{}
+	return NoopTracer[cohere.RerankV2Request, cohere.RerankV2Response, struct{}]{}
 }
 
 // Shutdown implements Tracing.Shutdown.
@@ -165,10 +165,10 @@ func (NoopTracing) Shutdown(context.Context) error {
 }
 
 // NoopTracer implements RequestTracer without producing spans.
-type NoopTracer[ReqT any, SpanT any] struct{}
+type NoopTracer[ReqT any, RespT any, RespChunkT any] struct{}
 
 // StartSpanAndInjectHeaders implements RequestTracer.StartSpanAndInjectHeaders.
-func (NoopTracer[ReqT, SpanT]) StartSpanAndInjectHeaders(context.Context, map[string]string, propagation.TextMapCarrier, *ReqT, []byte) SpanT {
-	var zero SpanT
+func (NoopTracer[ReqT, RespT, RespChunkT]) StartSpanAndInjectHeaders(context.Context, map[string]string, propagation.TextMapCarrier, *ReqT, []byte) Span[RespT, RespChunkT] {
+	var zero Span[RespT, RespChunkT]
 	return zero
 }

internal/tracing/api/api_test.go

@@ -16,7 +16,7 @@ import (
 
 func TestNoopTracing(t *testing.T) {
 	tracing := NoopTracing{}
-	require.IsType(t, NoopTracer[openai.ChatCompletionRequest, ChatCompletionSpan]{}, tracing.ChatCompletionTracer())
+	require.IsType(t, NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{}, tracing.ChatCompletionTracer())
 	require.Equal(t, NoopMCPTracer{}, tracing.MCPTracer())
 
 	// Calling shutdown twice should not cause an error.
@@ -25,7 +25,7 @@ func TestNoopTracing(t *testing.T) {
 }
 
 func TestNoopTracerChatCompletion(t *testing.T) {
-	tracer := NoopTracer[openai.ChatCompletionRequest, ChatCompletionSpan]{}
+	tracer := NoopTracer[openai.ChatCompletionRequest, openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]{}
 
 	readHeaders := map[string]string{}
 	writeHeaders := propagation.MapCarrier{}

internal/tracing/span.go

@@ -19,7 +19,7 @@ type responseRecorder[RespT any] interface {
 	RecordResponseOnError(trace.Span, int, []byte)
 }
 
-type streamResponseRecorder[ChunkT any, RespT any] interface {
+type streamResponseRecorder[RespT, ChunkT any] interface {
 	responseRecorder[RespT]
 	RecordResponseChunks(trace.Span, []*ChunkT)
 }
@@ -28,58 +28,58 @@ type noopChunkRecorder[ChunkT any] struct{}
 
 func (noopChunkRecorder[ChunkT]) RecordResponseChunk(*ChunkT) {}
 
-type streamingSpan[ChunkT any, RespT any, Recorder streamResponseRecorder[ChunkT, RespT]] struct {
+type streamingSpan[RespT, ChunkT any] struct {
 	span     trace.Span
-	recorder Recorder
+	recorder streamResponseRecorder[RespT, ChunkT]
 	chunks   []*ChunkT
 }
 
-func (s *streamingSpan[ChunkT, RespT, Recorder]) RecordResponseChunk(resp *ChunkT) {
+func (s *streamingSpan[RespT, ChunkT]) RecordResponseChunk(resp *ChunkT) {
 	s.chunks = append(s.chunks, resp)
 }
 
-func (s *streamingSpan[ChunkT, RespT, Recorder]) RecordResponse(resp *RespT) {
+func (s *streamingSpan[RespT, ChunkT]) RecordResponse(resp *RespT) {
 	s.recorder.RecordResponse(s.span, resp)
 }
 
-func (s *streamingSpan[ChunkT, RespT, Recorder]) EndSpan() {
+func (s *streamingSpan[RespT, ChunkT]) EndSpan() {
 	if len(s.chunks) > 0 {
 		s.recorder.RecordResponseChunks(s.span, s.chunks)
 	}
 	s.span.End()
 }
 
-func (s *streamingSpan[ChunkT, RespT, Recorder]) EndSpanOnError(statusCode int, body []byte) {
+func (s *streamingSpan[RespT, ChunkT]) EndSpanOnError(statusCode int, body []byte) {
 	s.recorder.RecordResponseOnError(s.span, statusCode, body)
 	s.span.End()
 }
 
-type responseSpan[ChunkT any, RespT any, Recorder responseRecorder[RespT]] struct {
+type responseSpan[RespT, ChunkT any] struct {
 	noopChunkRecorder[ChunkT]
 	span     trace.Span
-	recorder Recorder
+	recorder streamResponseRecorder[RespT, ChunkT]
 }
 
-func (s *responseSpan[ChunkT, RespT, Recorder]) RecordResponse(resp *RespT) {
+func (s *responseSpan[RespT, ChunkT]) RecordResponse(resp *RespT) {
 	s.recorder.RecordResponse(s.span, resp)
 }
 
-func (s *responseSpan[ChunkT, RespT, Recorder]) EndSpan() {
+func (s *responseSpan[RespT, ChunkT]) EndSpan() {
 	s.span.End()
 }
 
-func (s *responseSpan[ChunkT, RespT, Recorder]) EndSpanOnError(statusCode int, body []byte) {
+func (s *responseSpan[RespT, ChunkT]) EndSpanOnError(statusCode int, body []byte) {
 	s.recorder.RecordResponseOnError(s.span, statusCode, body)
 	s.span.End()
 }
 
 // Type aliases tying generic implementations to concrete recorder contracts.
 type (
-	chatCompletionSpan  = streamingSpan[openai.ChatCompletionResponseChunk, openai.ChatCompletionResponse, tracing.ChatCompletionRecorder]
-	completionSpan      = streamingSpan[openai.CompletionResponse, openai.CompletionResponse, tracing.CompletionRecorder]
-	embeddingsSpan      = responseSpan[struct{}, openai.EmbeddingResponse, tracing.EmbeddingsRecorder]
-	imageGenerationSpan = responseSpan[struct{}, openaisdk.ImagesResponse, tracing.ImageGenerationRecorder]
-	rerankSpan          = responseSpan[struct{}, cohereschema.RerankV2Response, tracing.RerankRecorder]
+	chatCompletionSpan  = streamingSpan[openai.ChatCompletionResponse, openai.ChatCompletionResponseChunk]
+	completionSpan      = streamingSpan[openai.CompletionResponse, openai.CompletionResponse]
+	embeddingsSpan      = responseSpan[openai.EmbeddingResponse, struct{}]
+	imageGenerationSpan = responseSpan[openaisdk.ImagesResponse, struct{}]
+	rerankSpan          = responseSpan[cohereschema.RerankV2Response, struct{}]
 )
 
 var (