mcp-mesh 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

_mcp_mesh/tracing/execution_tracer.py

@@ -5,22 +5,19 @@ This class encapsulates all the execution logging logic to keep the dependency i
 """
 
 import logging
-import os
 import time
 from collections.abc import Callable
 from typing import Any, Optional
 
-logger = logging.getLogger(__name__)
-
+# Import shared utilities at module level to avoid circular imports during execution
+from .utils import (
+    generate_span_id,
+    get_agent_metadata_with_fallback,
+    is_tracing_enabled,
+    publish_trace_with_fallback,
+)
 
-def _is_tracing_enabled() -> bool:
-    """Check if distributed tracing is enabled via environment variable."""
-    return os.getenv("MCP_MESH_DISTRIBUTED_TRACING_ENABLED", "false").lower() in (
-        "true",
-        "1",
-        "yes",
-        "on",
-    )
+logger = logging.getLogger(__name__)
 
 
 class ExecutionTracer:
@@ -60,30 +57,24 @@ class ExecutionTracer:
             }
 
             # Add agent context metadata for distributed tracing
-            try:
-                from .agent_context_helper import get_trace_metadata
-
-                agent_metadata = get_trace_metadata()
-                self.execution_metadata.update(agent_metadata)
-            except Exception as e:
-                # Never fail execution due to agent metadata collection
-                self.logger.debug(f"Failed to get agent metadata: {e}")
-                # Add minimal fallback metadata
-                self.execution_metadata.update(
-                    {
-                        "agent_id": "unknown",
-                        "agent_name": "unknown",
-                        "agent_hostname": "unknown",
-                        "agent_ip": "unknown",
-                    }
-                )
+            agent_metadata = get_agent_metadata_with_fallback(self.logger)
+            self.execution_metadata.update(agent_metadata)
 
             if self.trace_context:
+                # Generate a new child span ID for this function execution
+                # Keep the same trace_id but create unique span_id per function call
+                function_span_id = generate_span_id()
+
+
                 self.execution_metadata.update(
                     {
                         "trace_id": self.trace_context.trace_id,
-                        "span_id": self.trace_context.span_id,
-                        "parent_span": self.trace_context.parent_span,
+                        "span_id": function_span_id,  # New child span for this function
+                        "parent_span": (
+                            self.trace_context.span_id
+                            if self.trace_context.parent_span is not None
+                            else None
+                        ),  # HTTP middleware span becomes parent only if not root
                     }
                 )
 
@@ -117,15 +108,7 @@ class ExecutionTracer:
             )
 
             # Save execution trace to Redis for distributed tracing storage
-            try:
-                from .redis_metadata_publisher import get_trace_publisher
-
-                publisher = get_trace_publisher()
-                if publisher.is_available:
-                    publisher.publish_execution_trace(self.execution_metadata)
-            except Exception as e:
-                # Never fail agent operations due to trace publishing
-                pass
+            publish_trace_with_fallback(self.execution_metadata, self.logger)
 
         except Exception as e:
             self.logger.warning(
@@ -149,7 +132,7 @@ class ExecutionTracer:
         exception handling and cleanup. If tracing is disabled, calls function directly.
         """
         # If tracing is disabled, call function directly without any overhead
-        if not _is_tracing_enabled():
+        if not is_tracing_enabled():
             return func(*args, **kwargs)
 
         tracer = ExecutionTracer(func.__name__, logger_instance)
@@ -176,7 +159,7 @@ class ExecutionTracer:
         If tracing is disabled, calls function directly.
         """
         # If tracing is disabled, call function directly without any overhead
-        if not _is_tracing_enabled():
+        if not is_tracing_enabled():
             return func(*args, **kwargs)
 
         tracer = ExecutionTracer(func.__name__, logger_instance)
@@ -209,9 +192,9 @@ class ExecutionTracer:
         exception handling and cleanup. If tracing is disabled, calls function directly.
         """
         import inspect
-        
+
         # If tracing is disabled, call function directly without any overhead
-        if not _is_tracing_enabled():
+        if not is_tracing_enabled():
             if inspect.iscoroutinefunction(func):
                 return await func(*args, **kwargs)
             else:

_mcp_mesh/tracing/fastapi_tracing_middleware.py

@@ -0,0 +1,204 @@
+"""
+FastAPI Tracing Middleware - Dedicated route-level tracing for FastAPI applications.
+
+This middleware provides clean separation from MCP agent tracing while ensuring
+FastAPI routes get comprehensive execution tracking and distributed tracing support.
+"""
+
+import logging
+import time
+from collections.abc import Callable
+
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.requests import Request
+from starlette.responses import Response
+
+logger = logging.getLogger(__name__)
+
+
+class FastAPITracingMiddleware(BaseHTTPMiddleware):
+    """Dedicated tracing middleware for FastAPI routes.
+
+    Provides route-level execution tracing with:
+    - Performance monitoring (request duration)
+    - Distributed tracing context setup
+    - Redis trace publishing
+    - Route name extraction
+    - Zero overhead when tracing disabled
+    """
+
+    def __init__(self, app, logger_instance: logging.Logger = None):
+        super().__init__(app)
+        self.logger = logger_instance or logger
+
+    async def dispatch(self, request: Request, call_next: Callable) -> Response:
+        """Process FastAPI request with comprehensive tracing."""
+
+        # If tracing is disabled, process request directly with zero overhead
+        from .utils import is_tracing_enabled
+
+        if not is_tracing_enabled():
+            return await call_next(request)
+
+
+        # Setup distributed tracing context from request headers
+        try:
+            from .trace_context_helper import TraceContextHelper
+
+            # Extract trace context from request headers
+            trace_context = await TraceContextHelper.extract_trace_context_from_request(
+                request
+            )
+
+
+            # Setup trace context for this request lifecycle
+            TraceContextHelper.setup_request_trace_context(trace_context, self.logger)
+
+        except Exception as e:
+            # Never fail request due to tracing issues
+            pass
+
+        # Extract route information for tracing
+        route_name = self._extract_route_name(request)
+        start_time = time.time()
+
+
+        try:
+            # Process the request
+            response = await call_next(request)
+
+            # Calculate performance metrics
+            end_time = time.time()
+            duration_ms = round((end_time - start_time) * 1000, 2)
+
+            # Publish route execution trace
+            self._publish_route_trace(
+                route_name=route_name,
+                request_method=request.method,
+                request_path=str(request.url.path),
+                start_time=start_time,
+                end_time=end_time,
+                duration_ms=duration_ms,
+                success=True,
+                status_code=response.status_code,
+            )
+
+
+            return response
+
+        except Exception as e:
+            # Calculate performance metrics for failed request
+            end_time = time.time()
+            duration_ms = round((end_time - start_time) * 1000, 2)
+
+            # Publish failed route execution trace
+            self._publish_route_trace(
+                route_name=route_name,
+                request_method=request.method,
+                request_path=str(request.url.path),
+                start_time=start_time,
+                end_time=end_time,
+                duration_ms=duration_ms,
+                success=False,
+                error=str(e),
+            )
+
+
+            raise  # Re-raise the original exception
+
+    def _extract_route_name(self, request: Request) -> str:
+        """Extract meaningful route name for tracing."""
+        try:
+            # Try to get route from FastAPI request state
+            if hasattr(request, "scope") and "route" in request.scope:
+                route = request.scope["route"]
+                if hasattr(route, "path"):
+                    return f"{request.method} {route.path}"
+
+            # Fallback to URL path
+            path = str(request.url.path)
+            return f"{request.method} {path}"
+
+        except Exception as e:
+            self.logger.debug(f"Failed to extract route name: {e}")
+            return f"{request.method} {request.url.path}"
+
+    def _publish_route_trace(
+        self,
+        route_name: str,
+        request_method: str,
+        request_path: str,
+        start_time: float,
+        end_time: float,
+        duration_ms: float,
+        success: bool,
+        status_code: int = None,
+        error: str = None,
+    ) -> None:
+        """Publish route execution trace to Redis."""
+        try:
+            from .context import TraceContext
+            from .redis_metadata_publisher import get_trace_publisher
+
+            # Get current trace context
+            current_trace = TraceContext.get_current()
+
+            if not current_trace:
+                return
+
+            # Generate a unique span ID for this route execution
+            from .utils import generate_span_id
+
+            route_span_id = generate_span_id()
+
+            # Build route execution metadata
+            execution_metadata = {
+                "function_name": route_name,
+                "route_name": route_name,
+                "request_method": request_method,
+                "request_path": request_path,
+                "start_time": start_time,
+                "end_time": end_time,
+                "duration_ms": duration_ms,
+                "success": success,
+                "error": error,
+                "status_code": status_code,
+                "trace_id": current_trace.trace_id,
+                "span_id": route_span_id,
+                "parent_span": (
+                    current_trace.span_id
+                    if current_trace.parent_span is not None
+                    else None
+                ),
+                "call_context": "fastapi_route_execution",
+                "agent_type": "fastapi_app",
+            }
+
+            # Add agent context metadata
+            from .utils import get_agent_metadata_with_fallback
+
+            agent_metadata = get_agent_metadata_with_fallback(self.logger)
+            # Override with FastAPI-specific values if fallback was used
+            if agent_metadata.get("agent_id") == "unknown":
+                agent_metadata.update(
+                    {"agent_id": "fastapi_app", "agent_name": "fastapi_app"}
+                )
+            execution_metadata.update(agent_metadata)
+
+            # Publish to Redis
+            from .utils import publish_trace_with_fallback
+
+            publish_trace_with_fallback(execution_metadata, self.logger)
+
+        except Exception as e:
+            # Never fail requests due to trace publishing
+            pass
+
+
+def get_fastapi_tracing_middleware() -> FastAPITracingMiddleware:
+    """Get FastAPI tracing middleware instance.
+
+    Returns:
+        Configured FastAPITracingMiddleware instance
+    """
+    return FastAPITracingMiddleware

_mcp_mesh/tracing/redis_metadata_publisher.py

@@ -39,18 +39,14 @@ class RedisTracePublisher:
 
     def _is_tracing_enabled(self) -> bool:
         """Check if distributed tracing is enabled via environment variable."""
-        return os.getenv("MCP_MESH_DISTRIBUTED_TRACING_ENABLED", "false").lower() in (
-            "true",
-            "1",
-            "yes",
-            "on",
-        )
+        from .utils import is_tracing_enabled
+
+        return is_tracing_enabled()
 
     def _init_redis(self):
         """Initialize Redis connection with graceful fallback (following session storage pattern)."""
         if not self._tracing_enabled:
             self._available = False
-            logger.info("Distributed tracing: disabled")
             return
 
         logger.info("Distributed tracing: enabled")
@@ -76,33 +72,23 @@ class RedisTracePublisher:
             return  # Silent no-op when Redis unavailable
 
         try:
-            # Add timestamp to trace data if not present
-            if "published_at" not in trace_data:
-                import time
-
-                trace_data["published_at"] = time.time()
-
-            # Convert complex types to JSON strings for Redis Stream storage
-            redis_trace_data = {}
-            for key, value in trace_data.items():
-                if isinstance(value, (list, dict)):
-                    # Convert lists and dicts to JSON strings
-                    import json
-
-                    redis_trace_data[key] = json.dumps(value)
-                elif value is None:
-                    redis_trace_data[key] = "null"
-                else:
-                    # Keep simple types as-is (str, int, float, bool)
-                    redis_trace_data[key] = str(value)
+            function_name = trace_data.get("function_name", "unknown")
+            trace_id = trace_data.get("trace_id", "no-trace-id")
+
+            # Add timestamp and convert for Redis storage
+            from .utils import add_timestamp_if_missing, convert_for_redis_storage
+
+            add_timestamp_if_missing(trace_data)
+            redis_trace_data = convert_for_redis_storage(trace_data)
 
             # Publish to Redis Stream
             if self._redis_client:
-                self._redis_client.xadd(self.stream_name, redis_trace_data)
+                message_id = self._redis_client.xadd(self.stream_name, redis_trace_data)
+                logger.debug(f"Published trace for '{function_name}' to Redis stream")
 
         except Exception as e:
             # Non-blocking - never fail agent operations due to trace publishing
-            logger.warning(f"Failed to publish execution trace to Redis: {e}")
+            pass
 
     @property
     def is_available(self) -> bool:
@@ -151,9 +137,3 @@ def get_trace_publisher() -> RedisTracePublisher:
     if _trace_publisher is None:
         _trace_publisher = RedisTracePublisher()
     return _trace_publisher
-
-
-# Legacy alias for backward compatibility
-def get_metadata_publisher() -> RedisTracePublisher:
-    """Legacy alias for get_trace_publisher - use get_trace_publisher instead."""
-    return get_trace_publisher()

_mcp_mesh/tracing/trace_context_helper.py

@@ -4,24 +4,13 @@ Trace Context Helper - Helper class for HTTP request trace context setup.
 This class encapsulates all the trace context setup logic to keep HTTP wrappers clean.
 """
 
+import json
 import logging
-import os
-import uuid
 from typing import Any, Optional
 
 logger = logging.getLogger(__name__)
 
 
-def _is_tracing_enabled() -> bool:
-    """Check if distributed tracing is enabled via environment variable."""
-    return os.getenv("MCP_MESH_DISTRIBUTED_TRACING_ENABLED", "false").lower() in (
-        "true",
-        "1",
-        "yes",
-        "on",
-    )
-
-
 class TraceContextHelper:
     """Helper class to handle HTTP request trace context setup and distributed tracing."""
 
@@ -36,7 +25,9 @@ class TraceContextHelper:
         If tracing is disabled, this function returns immediately without setting up trace context.
         """
         # If tracing is disabled, skip all trace context setup
-        if not _is_tracing_enabled():
+        from .utils import is_tracing_enabled
+
+        if not is_tracing_enabled():
             return
 
         try:
@@ -46,7 +37,9 @@ class TraceContextHelper:
             extracted_trace_id = trace_context.get("trace_id")
             if extracted_trace_id and extracted_trace_id.strip():
                 # EXISTING TRACE: This service is being called by another service
-                current_span_id = str(uuid.uuid4())
+                from .utils import generate_span_id
+
+                current_span_id = generate_span_id()
                 parent_span_id = trace_context.get("parent_span")
 
                 # Set context that will be used throughout request lifecycle
@@ -57,8 +50,10 @@ class TraceContextHelper:
                 )
             else:
                 # NEW ROOT TRACE: This service is the entry point (no incoming trace headers)
-                root_trace_id = str(uuid.uuid4())
-                root_span_id = str(uuid.uuid4())
+                from .utils import generate_span_id, generate_trace_id
+
+                root_trace_id = generate_trace_id()
+                root_span_id = generate_span_id()
 
                 # Set context for root trace (no parent_span)
                 TraceContext.set_current(
@@ -101,8 +96,6 @@ class TraceContextHelper:
         # Try extracting from JSON-RPC body as fallback
         if not trace_id:
             try:
-                import json
-
                 body = await request.body()
                 if body:
                     payload = json.loads(body.decode("utf-8"))
@@ -156,7 +149,9 @@ class TraceContextHelper:
         If tracing is disabled, this function returns immediately without modifying headers.
         """
         # If tracing is disabled, skip all trace header injection
-        if not _is_tracing_enabled():
+        from .utils import is_tracing_enabled
+
+        if not is_tracing_enabled():
             return
 
         try:

_mcp_mesh/tracing/utils.py

@@ -0,0 +1,137 @@
+"""
+Shared tracing utilities for MCP Mesh distributed tracing.
+
+Provides common functions used across multiple tracing modules to reduce code duplication
+and maintain consistency.
+"""
+
+import json
+import logging
+import os
+import time
+import uuid
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def is_tracing_enabled() -> bool:
+    """Check if distributed tracing is enabled via environment variable.
+
+    Returns:
+        True if tracing is enabled, False otherwise
+    """
+    return os.getenv("MCP_MESH_DISTRIBUTED_TRACING_ENABLED", "false").lower() in (
+        "true",
+        "1",
+        "yes",
+        "on",
+    )
+
+
+def generate_span_id() -> str:
+    """Generate a unique span ID for tracing.
+
+    Returns:
+        UUID string for span identification
+    """
+    return str(uuid.uuid4())
+
+
+def generate_trace_id() -> str:
+    """Generate a unique trace ID for tracing.
+
+    Returns:
+        UUID string for trace identification
+    """
+    return str(uuid.uuid4())
+
+
+def get_agent_metadata_with_fallback(logger_instance: logging.Logger) -> dict[str, Any]:
+    """Get agent context metadata with graceful fallback.
+
+    Attempts to retrieve agent metadata from the context helper, falling back
+    to minimal defaults if unavailable. Never fails execution.
+
+    Args:
+        logger_instance: Logger for debug messages
+
+    Returns:
+        Dictionary containing agent metadata
+    """
+    try:
+        from .agent_context_helper import get_trace_metadata
+
+        return get_trace_metadata()
+    except Exception as e:
+        # Never fail execution due to agent metadata collection
+        logger_instance.debug(f"Failed to get agent metadata: {e}")
+        # Return minimal fallback metadata
+        return {
+            "agent_id": "unknown",
+            "agent_name": "unknown",
+            "agent_hostname": "unknown",
+            "agent_ip": "unknown",
+        }
+
+
+def publish_trace_with_fallback(
+    trace_data: dict[str, Any], logger_instance: logging.Logger
+) -> None:
+    """Publish trace data to Redis with graceful fallback.
+
+    Attempts to publish trace data to Redis, silently handling failures
+    to ensure trace publishing never breaks application execution.
+
+    Args:
+        trace_data: Trace metadata to publish
+        logger_instance: Logger for debug messages
+    """
+    try:
+        from .redis_metadata_publisher import get_trace_publisher
+
+        publisher = get_trace_publisher()
+        if publisher.is_available:
+            publisher.publish_execution_trace(trace_data)
+            pass
+        else:
+            pass
+    except Exception as e:
+        # Never fail agent operations due to trace publishing
+        pass
+
+
+def add_timestamp_if_missing(trace_data: dict[str, Any]) -> None:
+    """Add published_at timestamp to trace data if not present.
+
+    Args:
+        trace_data: Trace data dictionary to modify in-place
+    """
+    if "published_at" not in trace_data:
+        trace_data["published_at"] = time.time()
+
+
+def convert_for_redis_storage(trace_data: dict[str, Any]) -> dict[str, str]:
+    """Convert trace data for Redis Stream storage.
+
+    Converts complex types (lists, dicts) to JSON strings and handles None values
+    for proper Redis Stream storage.
+
+    Args:
+        trace_data: Original trace data with mixed types
+
+    Returns:
+        Dictionary with all values converted to strings suitable for Redis
+    """
+    redis_trace_data = {}
+    for key, value in trace_data.items():
+        if isinstance(value, (list, dict)):
+            # Convert lists and dicts to JSON strings
+            redis_trace_data[key] = json.dumps(value)
+        elif value is None:
+            redis_trace_data[key] = "null"
+        else:
+            # Keep simple types as-is (str, int, float, bool)
+            redis_trace_data[key] = str(value)
+
+    return redis_trace_data

{mcp_mesh-0.5.1.dist-info → mcp_mesh-0.5.3.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-mesh
-Version: 0.5.1
+Version: 0.5.3
 Summary: Kubernetes-native platform for distributed MCP applications
 Project-URL: Homepage, https://github.com/dhyansraj/mcp-mesh
 Project-URL: Documentation, https://github.com/dhyansraj/mcp-mesh/tree/main/docs