adde semconv file, client span name changed, new folder name, mcpinstrumentor as an entry point

Author: Johnnyl202

aws-opentelemetry-distro/pyproject.toml

@@ -21,8 +21,6 @@ classifiers = [
   "Programming Language :: Python :: 3.9",
   "Programming Language :: Python :: 3.10",
   "Programming Language :: Python :: 3.11",
-  "Programming Language :: Python :: 3.12",
-  "Programming Language :: Python :: 3.13",
 ]
 
 dependencies = [
@@ -89,12 +87,16 @@ dependencies = [
 # If a new patch is added into the list, it must also be added into tox.ini, dev-requirements.txt and _instrumentation_patch
 patch = [
   "botocore ~= 1.0",
+  "mcp >= 1.1.0"
 ]
 test = []
 
 [project.entry-points.opentelemetry_configurator]
 aws_configurator = "amazon.opentelemetry.distro.aws_opentelemetry_configurator:AwsOpenTelemetryConfigurator"
 
+[project.entry-points.opentelemetry_instrumentor]
+mcp = "amazon.opentelemetry.distro.instrumentation.mcp.mcp_instrumentor:MCPInstrumentor"
+
 [project.entry-points.opentelemetry_distro]
 aws_distro = "amazon.opentelemetry.distro.aws_opentelemetry_distro:AwsOpenTelemetryDistro"
 
@@ -111,4 +113,4 @@ include = [
 ]
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/amazon"]
+packages = ["src/amazon"]

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/instrumentation/mcp/README.md

@@ -0,0 +1,28 @@
+# MCP Instrumentor
+
+OpenTelemetry instrumentation for Model Context Protocol (MCP).
+
+## Installation
+
+Included in AWS OpenTelemetry Distro:
+
+```bash
+pip install aws-opentelemetry-distro
+```
+
+## Usage
+
+Automatically enabled with:
+
+```bash
+opentelemetry-instrument python your_mcp_app.py
+```
+
+## Configuration
+
+- `MCP_INSTRUMENTATION_SERVER_NAME`: Override default server name (default: "mcp server")
+
+## Spans Created
+
+- **Client**: `client.send_request` 
+- **Server**: `tools/initialize`, `tools/list`, `tools/{tool_name}`

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/instrumentation/mcp/__init__.py

@@ -0,0 +1,2 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/mcpinstrumentor/mcpinstrumentor.py renamed to aws-opentelemetry-distro/src/amazon/opentelemetry/distro/instrumentation/mcp/mcp_instrumentor.py

@@ -8,7 +8,7 @@
 from opentelemetry import trace
 from opentelemetry.instrumentation.instrumentor import BaseInstrumentor
 from opentelemetry.instrumentation.utils import unwrap
-
+from .semconv import MCPAttributes, MCPSpanNames, MCPOperations, MCPTraceContext, MCPEnvironmentVariables
 _instruments = ("mcp >= 1.6.0",)
 
 class MCPInstrumentor(BaseInstrumentor):
@@ -27,9 +27,9 @@ def instrumentation_dependencies() -> Collection[str]:
     def _instrument(self, **kwargs: Any) -> None:
         tracer_provider = kwargs.get("tracer_provider")
         if tracer_provider:
-            self.tracer = tracer_provider.get_tracer("mcp")
+            self.tracer = tracer_provider.get_tracer("instrumentation.mcp")
         else:
-            self.tracer = trace.get_tracer("mcp")
+            self.tracer = trace.get_tracer("instrumentation.mcp")
         register_post_import_hook(
             lambda _: wrap_function_wrapper(
                 "mcp.shared.session",
@@ -65,7 +65,7 @@ def _wrap_send_request(
         """
 
         async def async_wrapper():
-            with self.tracer.start_as_current_span("client.send_request", kind=trace.SpanKind.CLIENT) as span:
+            with self.tracer.start_as_current_span(MCPSpanNames.CLIENT_SEND_REQUEST, kind=trace.SpanKind.CLIENT) as span:
                 span_ctx = span.get_span_context()
                 request = args[0] if len(args) > 0 else kwargs.get("request")
                 if request:
@@ -107,7 +107,7 @@ async def _wrap_handle_request(
         traceparent = None
 
         if req and hasattr(req, "params") and req.params and hasattr(req.params, "meta") and req.params.meta:
-            traceparent = getattr(req.params.meta, "traceparent", None)
+            traceparent = getattr(req.params.meta, MCPTraceContext.TRACEPARENT_HEADER, None)
         span_context = self._extract_span_context_from_traceparent(traceparent) if traceparent else None
         if span_context:
             span_name = self._get_mcp_operation(req)
@@ -125,16 +125,24 @@ async def _wrap_handle_request(
     def _generate_mcp_attributes(self, span: trace.Span, request: ClientRequest, is_client: bool) -> None:
         import mcp.types as types  # pylint: disable=import-outside-toplevel,consider-using-from-import
 
-        operation = "UnknownOperation"
+        operation = MCPOperations.UNKNOWN_OPERATION
+        
         if isinstance(request, types.ListToolsRequest):
-            operation = "ListTool"
-            span.set_attribute("mcp.list_tools", True)
+            operation = MCPOperations.LIST_TOOL
+            span.set_attribute(MCPAttributes.MCP_LIST_TOOLS, True)
+            if is_client:
+                span.update_name(MCPSpanNames.CLIENT_LIST_TOOLS)
         elif isinstance(request, types.CallToolRequest):
             operation = request.params.name
-            span.set_attribute("mcp.call_tool", True)
+            span.set_attribute(MCPAttributes.MCP_CALL_TOOL, True)
+            if is_client:
+                span.update_name(MCPSpanNames.client_call_tool(request.params.name))
         elif isinstance(request, types.InitializeRequest):
-            operation = "Initialize"
-            span.set_attribute("mcp.initialize", True)
+            operation = MCPOperations.INITIALIZE
+            span.set_attribute(MCPAttributes.MCP_INITIALIZE, True)
+            if is_client:
+                span.update_name(MCPSpanNames.CLIENT_INITIALIZE)
+        
         if is_client:
             self._add_client_attributes(span, operation, request)
         else:
@@ -148,9 +156,9 @@ def _inject_trace_context(request_data: Dict[str, Any], span_ctx) -> None:
             request_data["params"]["_meta"] = {}
         trace_id_hex = f"{span_ctx.trace_id:032x}"
         span_id_hex = f"{span_ctx.span_id:016x}"
-        trace_flags = "01"
-        traceparent = f"00-{trace_id_hex}-{span_id_hex}-{trace_flags}"
-        request_data["params"]["_meta"]["traceparent"] = traceparent
+        trace_flags = MCPTraceContext.TRACE_FLAGS_SAMPLED
+        traceparent = f"{MCPTraceContext.TRACEPARENT_VERSION}-{trace_id_hex}-{span_id_hex}-{trace_flags}"
+        request_data["params"]["_meta"][MCPTraceContext.TRACEPARENT_HEADER] = traceparent
 
     @staticmethod
     def _extract_span_context_from_traceparent(traceparent: str):
@@ -177,24 +185,24 @@ def _get_mcp_operation(req: ClientRequest) -> str:
         span_name = "unknown"
 
         if isinstance(req, types.ListToolsRequest):
-            span_name = "tools/list"
+            span_name = MCPSpanNames.TOOLS_LIST
         elif isinstance(req, types.CallToolRequest):
-            span_name = f"tools/{req.params.name}"
+            span_name = MCPSpanNames.tools_call(req.params.name)
         elif isinstance(req, types.InitializeRequest):
-            span_name = "tools/initialize"
+            span_name = MCPSpanNames.TOOLS_INITIALIZE
         return span_name
 
     @staticmethod
     def _add_client_attributes(span: trace.Span, operation: str, request: ClientRequest) -> None:
         import os  # pylint: disable=import-outside-toplevel
 
-        service_name = os.environ.get("MCP_INSTRUMENTATION_SERVER_NAME", "mcp server")
-        span.set_attribute("aws.remote.service", service_name)
-        span.set_attribute("aws.remote.operation", operation)
+        service_name = os.environ.get(MCPEnvironmentVariables.SERVER_NAME, "mcp server")
+        span.set_attribute(MCPAttributes.AWS_REMOTE_SERVICE, service_name)
+        span.set_attribute(MCPAttributes.AWS_REMOTE_OPERATION, operation)
         if hasattr(request, "params") and request.params and hasattr(request.params, "name"):
-            span.set_attribute("tool.name", request.params.name)
+            span.set_attribute(MCPAttributes.MCP_TOOL_NAME, request.params.name)
 
     @staticmethod
     def _add_server_attributes(span: trace.Span, operation: str, request: ClientRequest) -> None:
         if hasattr(request, "params") and request.params and hasattr(request.params, "name"):
-            span.set_attribute("tool.name", request.params.name)
+            span.set_attribute(MCPAttributes.MCP_TOOL_NAME, request.params.name)

aws-opentelemetry-distro/src/amazon/opentelemetry/distro/instrumentation/mcp/semconv.py

@@ -0,0 +1,155 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+MCP (Model Context Protocol) Semantic Conventions for OpenTelemetry.
+
+This module defines semantic conventions for MCP instrumentation following
+OpenTelemetry standards for consistent telemetry data.
+"""
+
+
+class MCPAttributes:
+    """MCP-specific span attributes for OpenTelemetry instrumentation."""
+
+    # MCP Operation Type Attributes
+    MCP_INITIALIZE = "mcp.initialize"
+    """
+    Boolean attribute indicating this span represents an MCP initialize operation.
+    Set to True when the span tracks session initialization between client and server.
+    """
+
+    MCP_LIST_TOOLS = "mcp.list_tools"
+    """
+    Boolean attribute indicating this span represents an MCP list tools operation.
+    Set to True when the span tracks discovery of available tools on the server.
+    """
+
+    MCP_CALL_TOOL = "mcp.call_tool"
+    """
+    Boolean attribute indicating this span represents an MCP call tool operation.
+    Set to True when the span tracks execution of a specific tool.
+    """
+
+    # MCP Tool Information
+    MCP_TOOL_NAME = "mcp.tool.name"
+    """
+    The name of the MCP tool being called.
+    Example: "echo", "search", "calculator"
+    """
+
+    # AWS-specific Remote Service Attributes
+    AWS_REMOTE_SERVICE = "aws.remote.service"
+    """
+    The name of the remote MCP service being called.
+    Default: "mcp server" (can be overridden via MCP_INSTRUMENTATION_SERVER_NAME env var)
+    """
+
+    AWS_REMOTE_OPERATION = "aws.remote.operation"
+    """
+    The specific MCP operation being performed.
+    Values: "Initialize", "ListTool", or the specific tool name for call operations
+    """
+
+
+class MCPSpanNames:
+    """Standard span names for MCP operations."""
+
+    # Client-side span names
+    CLIENT_SEND_REQUEST = "client.send_request"
+    """
+    Span name for client-side MCP request operations.
+    Used for all outgoing MCP requests (initialize, list tools, call tool).
+    """
+
+    CLIENT_INITIALIZE = "mcp.initialize"
+    """
+    Span name for client-side MCP initialization requests.
+    """
+
+    CLIENT_LIST_TOOLS = "mcp.list_tools"
+    """
+    Span name for client-side MCP list tools requests.
+    """
+
+    @staticmethod
+    def client_call_tool(tool_name: str) -> str:
+        """
+        Generate span name for client-side MCP tool call requests.
+
+        Args:
+            tool_name: Name of the tool being called
+
+        Returns:
+            Formatted span name like "mcp.call_tool.echo", "mcp.call_tool.search"
+        """
+        return f"mcp.call_tool.{tool_name}"
+
+    # Server-side span names
+    TOOLS_INITIALIZE = "tools/initialize"
+    """
+    Span name for server-side MCP initialization handling.
+    Tracks server processing of client initialization requests.
+    """
+
+    TOOLS_LIST = "tools/list"
+    """
+    Span name for server-side MCP list tools handling.
+    Tracks server processing of tool discovery requests.
+    """
+
+    @staticmethod
+    def tools_call(tool_name: str) -> str:
+        """
+        Generate span name for server-side MCP tool call handling.
+
+        Args:
+            tool_name: Name of the tool being called
+
+        Returns:
+            Formatted span name like "tools/echo", "tools/search"
+        """
+        return f"tools/{tool_name}"
+
+
+class MCPOperations:
+    """Standard operation names for MCP semantic conventions."""
+
+    INITIALIZE = "Initialize"
+    """Operation name for MCP session initialization."""
+
+    LIST_TOOL = "ListTool"
+    """Operation name for MCP tool discovery."""
+
+    UNKNOWN_OPERATION = "UnknownOperation"
+    """Fallback operation name for unrecognized MCP operations."""
+
+
+class MCPTraceContext:
+    """Constants for MCP distributed tracing context propagation."""
+
+    TRACEPARENT_HEADER = "traceparent"
+    """
+    W3C Trace Context traceparent header name.
+    Used for propagating trace context in MCP request metadata.
+    """
+
+    TRACE_FLAGS_SAMPLED = "01"
+    """
+    W3C Trace Context flags indicating the trace is sampled.
+    """
+
+    TRACEPARENT_VERSION = "00"
+    """
+    W3C Trace Context version identifier.
+    """
+
+
+class MCPEnvironmentVariables:
+    """Environment variable names for MCP instrumentation configuration."""
+
+    SERVER_NAME = "MCP_INSTRUMENTATION_SERVER_NAME"
+    """
+    Environment variable to override the default MCP server name.
+    Default value: "mcp server"
+    """