Rename span attributes to MCP OTEL semantic conventions

pkg/telemetry/integration_test.go

@@ -233,7 +233,7 @@ func TestTelemetryIntegration_WithRealProviders(t *testing.T) {
 	require.Len(t, spans, 1)
 
 	span := spans[0]
-	assert.Equal(t, "mcp.tools/call", span.Name)
+	assert.Equal(t, "tools/call", span.Name)
 
 	// Verify span attributes
 	attrs := span.Attributes
@@ -242,14 +242,22 @@ func TestTelemetryIntegration_WithRealProviders(t *testing.T) {
 		attrMap[string(attr.Key)] = attr.Value.AsInterface()
 	}
 
+	// New OTEL semantic convention attributes (always present)
+	assert.Equal(t, "tools/call", attrMap["mcp.method.name"])
+	assert.Equal(t, testToolName, attrMap["gen_ai.tool.name"])
+	assert.Equal(t, "test-123", attrMap["jsonrpc.request.id"])
+	assert.Equal(t, "POST", attrMap["http.request.method"])
+	assert.Equal(t, int64(200), attrMap["http.response.status_code"])
+
+	// Legacy attributes (present because UseLegacyAttributes=true)
 	assert.Equal(t, "tools/call", attrMap["mcp.method"])
 	assert.Equal(t, testToolName, attrMap["mcp.tool.name"])
 	assert.Equal(t, "test-123", attrMap["mcp.request.id"])
 	assert.Equal(t, "POST", attrMap["http.method"])
 	assert.Equal(t, int64(200), attrMap["http.status_code"])
 
-	// Verify sensitive data is redacted
-	if toolArgs, exists := attrMap["mcp.tool.arguments"]; exists {
+	// Verify sensitive data is redacted in new attribute name
+	if toolArgs, exists := attrMap["gen_ai.tool.call.arguments"]; exists {
 		argsStr := toolArgs.(string)
 		assert.Contains(t, argsStr, "api_key=[REDACTED]")
 		assert.Contains(t, argsStr, "query=test query")

pkg/telemetry/middleware.go

@@ -29,6 +29,12 @@ import (
 const (
 	// instrumentationName is the name of this instrumentation package
 	instrumentationName = "github.com/stacklok/toolhive/pkg/telemetry"
+	// methodPromptsGet is the MCP method name for prompts/get
+	methodPromptsGet = "prompts/get"
+	// networkTransportTCP is the OTEL value for TCP transport
+	networkTransportTCP = "tcp"
+	// networkProtocolHTTP is the OTEL value for HTTP protocol
+	networkProtocolHTTP = "http"
 )
 
 // HTTPMiddleware provides OpenTelemetry instrumentation for HTTP requests.
@@ -125,7 +131,10 @@ func (m *HTTPMiddleware) Handler(next http.Handler) http.Handler {
 		))
 
 		// Create span name based on MCP method if available, otherwise use HTTP method + path
-		spanName := m.createSpanName(ctx, r)
+		spanName := m.createSpanName(ctx)
+		if spanName == "" {
+			spanName = fmt.Sprintf("%s %s", r.Method, r.URL.Path)
+		}
 		ctx, span := m.tracer.Start(ctx, spanName, trace.WithSpanKind(trace.SpanKindServer))
 		defer span.End()
 
@@ -158,19 +167,35 @@ func (m *HTTPMiddleware) Handler(next http.Handler) http.Handler {
 	})
 }
 
-// createSpanName creates an appropriate span name based on available context.
-func (*HTTPMiddleware) createSpanName(ctx context.Context, r *http.Request) string {
-	// Try to get MCP method from parsed data
-	if mcpMethod := mcpparser.GetMCPMethod(ctx); mcpMethod != "" {
-		return fmt.Sprintf("mcp.%s", mcpMethod)
+func (*HTTPMiddleware) createSpanName(ctx context.Context) string {
+	parsedMCP := mcpparser.GetParsedMCPRequest(ctx)
+	if parsedMCP == nil || parsedMCP.Method == "" {
+		return ""
 	}
-
-	// Fall back to HTTP method + path
-	return fmt.Sprintf("%s %s", r.Method, r.URL.Path)
+	return parsedMCP.Method
 }
 
 // addHTTPAttributes adds standard HTTP attributes to the span.
 func (m *HTTPMiddleware) addHTTPAttributes(span trace.Span, r *http.Request) {
+	// New OTEL HTTP semantic convention attributes (always emitted)
+	span.SetAttributes(
+		attribute.String("http.request.method", r.Method),
+		attribute.String("url.full", r.URL.String()),
+		attribute.String("url.scheme", r.URL.Scheme),
+		attribute.String("server.address", r.Host),
+		attribute.String("url.path", r.URL.Path),
+		attribute.String("user_agent.original", r.UserAgent()),
+	)
+
+	if r.ContentLength > 0 {
+		span.SetAttributes(attribute.Int64("http.request.body.size", r.ContentLength))
+	}
+
+	if r.URL.RawQuery != "" {
+		span.SetAttributes(attribute.String("url.query", r.URL.RawQuery))
+	}
+
+	// Legacy attribute names (emitted only when UseLegacyAttributes is true)
 	if m.config.UseLegacyAttributes {
 		span.SetAttributes(
 			attribute.String("http.method", r.Method),
@@ -181,12 +206,10 @@ func (m *HTTPMiddleware) addHTTPAttributes(span trace.Span, r *http.Request) {
 			attribute.String("http.user_agent", r.UserAgent()),
 		)
 
-		// Add content length if available
 		if contentLength := r.Header.Get("Content-Length"); contentLength != "" {
 			span.SetAttributes(attribute.String("http.request_content_length", contentLength))
 		}
 
-		// Add query parameters if present
 		if r.URL.RawQuery != "" {
 			span.SetAttributes(attribute.String("http.query", r.URL.RawQuery))
 		}
@@ -219,20 +242,37 @@ func (m *HTTPMiddleware) addMCPAttributes(ctx context.Context, span trace.Span,
 		return
 	}
 
+	// New OTEL MCP semantic convention attributes (always emitted)
+	span.SetAttributes(
+		attribute.String("mcp.method.name", parsedMCP.Method),
+		attribute.String("rpc.system.name", "jsonrpc"),
+		attribute.String("jsonrpc.protocol.version", "2.0"),
+	)
+
+	if parsedMCP.ID != nil {
+		span.SetAttributes(attribute.String("jsonrpc.request.id", formatRequestID(parsedMCP.ID)))
+	}
+
+	// Resource URI: only set for resource-related methods
+	if parsedMCP.ResourceID != "" {
+		switch parsedMCP.Method {
+		case "resources/read", "resources/subscribe", "resources/unsubscribe", "notifications/resources/updated":
+			span.SetAttributes(attribute.String("mcp.resource.uri", parsedMCP.ResourceID))
+		}
+	}
+
+	// Legacy attribute names (emitted only when UseLegacyAttributes is true)
 	if m.config.UseLegacyAttributes {
-		// Add basic MCP attributes
 		span.SetAttributes(
 			attribute.String("mcp.method", parsedMCP.Method),
 			attribute.String("rpc.system", "jsonrpc"),
 			attribute.String("rpc.service", "mcp"),
 		)
 
-		// Add request ID if available
 		if parsedMCP.ID != nil {
 			span.SetAttributes(attribute.String("mcp.request.id", formatRequestID(parsedMCP.ID)))
 		}
 
-		// Add resource ID if available
 		if parsedMCP.ResourceID != "" {
 			span.SetAttributes(attribute.String("mcp.resource.id", parsedMCP.ResourceID))
 		}
@@ -241,15 +281,21 @@ func (m *HTTPMiddleware) addMCPAttributes(ctx context.Context, span trace.Span,
 	// Add method-specific attributes
 	m.addMethodSpecificAttributes(span, parsedMCP)
 
-	// Extract server name from the request, defaulting to the middleware's configured server name
+	// Extract server name from the request
 	serverName := m.extractServerName(r)
 	span.SetAttributes(attribute.String("mcp.server.name", serverName))
 
-	// Determine backend transport type
-	// Note: ToolHive supports multiple transport types including stdio, sse, streamable-http
-	// The transport should never be empty as both CLI and API have fallbacks to "streamable-http"
-	// If transport is still empty, it indicates a configuration issue in middleware construction
+	// Determine backend transport type and map to OTEL network.transport
 	backendTransport := m.extractBackendTransport(r)
+	networkTransport, protocolName, protocolVersion := mapTransport(backendTransport)
+	span.SetAttributes(attribute.String("network.transport", networkTransport))
+	if protocolName != "" {
+		span.SetAttributes(attribute.String("network.protocol.name", protocolName))
+	}
+	if protocolVersion != "" {
+		span.SetAttributes(attribute.String("network.protocol.version", protocolVersion))
+	}
+
 	if m.config.UseLegacyAttributes {
 		span.SetAttributes(attribute.String("mcp.transport", backendTransport))
 	}
@@ -262,35 +308,43 @@ func (m *HTTPMiddleware) addMCPAttributes(ctx context.Context, span trace.Span,
 
 // addMethodSpecificAttributes adds attributes specific to certain MCP methods.
 func (m *HTTPMiddleware) addMethodSpecificAttributes(span trace.Span, parsedMCP *mcpparser.ParsedMCPRequest) {
-	if !m.config.UseLegacyAttributes {
-		return
-	}
-
 	switch parsedMCP.Method {
 	case string(mcp.MethodToolsCall):
-		// For tool calls, the ResourceID is the tool name
+		// New gen_ai namespace attributes (always emitted)
 		if parsedMCP.ResourceID != "" {
-			span.SetAttributes(attribute.String("mcp.tool.name", parsedMCP.ResourceID))
+			span.SetAttributes(attribute.String("gen_ai.tool.name", parsedMCP.ResourceID))
 		}
-		// Add sanitized arguments
-		if args := m.sanitizeArguments(parsedMCP.Arguments); args != "" {
-			span.SetAttributes(attribute.String("mcp.tool.arguments", args))
+		span.SetAttributes(attribute.String("gen_ai.operation.name", "execute_tool"))
+
+		sanitizedArgs := m.sanitizeArguments(parsedMCP.Arguments)
+		if sanitizedArgs != "" {
+			span.SetAttributes(attribute.String("gen_ai.tool.call.arguments", sanitizedArgs))
 		}
 
-	case "resources/read":
-		// For resource reads, the ResourceID is the URI
-		if parsedMCP.ResourceID != "" {
-			span.SetAttributes(attribute.String("mcp.resource.uri", parsedMCP.ResourceID))
+		// Legacy names
+		if m.config.UseLegacyAttributes {
+			if parsedMCP.ResourceID != "" {
+				span.SetAttributes(attribute.String("mcp.tool.name", parsedMCP.ResourceID))
+			}
+			if sanitizedArgs != "" {
+				span.SetAttributes(attribute.String("mcp.tool.arguments", sanitizedArgs))
+			}
 		}
 
-	case "prompts/get":
-		// For prompt gets, the ResourceID is the prompt name
+	case methodPromptsGet:
+		// New gen_ai namespace attribute (always emitted)
 		if parsedMCP.ResourceID != "" {
-			span.SetAttributes(attribute.String("mcp.prompt.name", parsedMCP.ResourceID))
+			span.SetAttributes(attribute.String("gen_ai.prompt.name", parsedMCP.ResourceID))
+		}
+
+		// Legacy name
+		if m.config.UseLegacyAttributes {
+			if parsedMCP.ResourceID != "" {
+				span.SetAttributes(attribute.String("mcp.prompt.name", parsedMCP.ResourceID))
+			}
 		}
 
 	case "initialize":
-		// For initialize, the ResourceID is the client name
 		if parsedMCP.ResourceID != "" {
 			span.SetAttributes(attribute.String("mcp.client.name", parsedMCP.ResourceID))
 		}
@@ -331,6 +385,19 @@ func (m *HTTPMiddleware) extractBackendTransport(r *http.Request) string {
 	return m.transport
 }
 
+func mapTransport(mcpTransport string) (networkTransport, protocolName, protocolVersion string) {
+	switch mcpTransport {
+	case "stdio":
+		return "pipe", "", ""
+	case "sse":
+		return networkTransportTCP, networkProtocolHTTP, "1.1"
+	case "streamable-http":
+		return networkTransportTCP, networkProtocolHTTP, "2"
+	default:
+		return networkTransportTCP, networkProtocolHTTP, ""
+	}
+}
+
 // sanitizeArguments converts arguments to a safe string representation.
 func (m *HTTPMiddleware) sanitizeArguments(arguments map[string]interface{}) string {
 	if len(arguments) == 0 {
@@ -397,7 +464,13 @@ func formatRequestID(id interface{}) string {
 
 // finalizeSpan adds response attributes and sets the span status.
 func (m *HTTPMiddleware) finalizeSpan(span trace.Span, rw *responseWriter, duration time.Duration) {
-	// Add response attributes
+	// New OTEL HTTP semantic convention response attributes (always emitted)
+	span.SetAttributes(
+		attribute.Int("http.response.status_code", rw.statusCode),
+		attribute.Int64("http.response.body.size", rw.bytesWritten),
+	)
+
+	// Legacy response attributes
 	if m.config.UseLegacyAttributes {
 		span.SetAttributes(
 			attribute.Int("http.status_code", rw.statusCode),
@@ -534,10 +607,18 @@ func (m *HTTPMiddleware) recordSSEConnection(ctx context.Context, r *http.Reques
 	m.addHTTPAttributes(span, r)
 
 	// Add SSE-specific attributes
+	networkTransport, protocolName, protocolVersion := mapTransport(m.transport)
 	span.SetAttributes(
 		attribute.String("sse.event_type", "connection_established"),
 		attribute.String("mcp.server.name", m.serverName),
+		attribute.String("network.transport", networkTransport),
 	)
+	if protocolName != "" {
+		span.SetAttributes(attribute.String("network.protocol.name", protocolName))
+	}
+	if protocolVersion != "" {
+		span.SetAttributes(attribute.String("network.protocol.version", protocolVersion))
+	}
 	if m.config.UseLegacyAttributes {
 		span.SetAttributes(attribute.String("mcp.transport", m.transport))
 	}