fast-agent-mcp 0.0.7__py3-none-any.whl

mcp_agent/logging/logger.py

@@ -0,0 +1,365 @@
+"""
+Logger module for the MCP Agent, which provides:
+- Local + optional remote event transport
+- Async event bus
+- OpenTelemetry tracing decorators (for distributed tracing)
+- Automatic injection of trace_id/span_id into events
+- Developer-friendly Logger that can be used anywhere
+"""
+
+import asyncio
+import threading
+import time
+
+from typing import Any, Dict
+
+from contextlib import asynccontextmanager, contextmanager
+
+from mcp_agent.logging.events import Event, EventContext, EventFilter, EventType
+from mcp_agent.logging.listeners import (
+    BatchingListener,
+    LoggingListener,
+    ProgressListener,
+)
+from mcp_agent.logging.transport import AsyncEventBus, EventTransport
+
+
+class Logger:
+    """
+    Developer-friendly logger that sends events to the AsyncEventBus.
+    - `type` is a broad category (INFO, ERROR, etc.).
+    - `name` can be a custom domain-specific event name, e.g. "ORDER_PLACED".
+    """
+
+    def __init__(self, namespace: str):
+        self.namespace = namespace
+        self.event_bus = AsyncEventBus.get()
+
+    def _ensure_event_loop(self):
+        """Ensure we have an event loop we can use."""
+        try:
+            return asyncio.get_running_loop()
+        except RuntimeError:
+            # If no loop is running, create a new one
+            loop = asyncio.new_event_loop()
+            asyncio.set_event_loop(loop)
+            return loop
+
+    def _emit_event(self, event: Event):
+        """Emit an event by running it in the event loop."""
+        loop = self._ensure_event_loop()
+        if loop.is_running():
+            # If we're in a thread with a running loop, schedule the coroutine
+            asyncio.create_task(self.event_bus.emit(event))
+        else:
+            # If no loop is running, run it until the emit completes
+            loop.run_until_complete(self.event_bus.emit(event))
+
+    def event(
+        self,
+        etype: EventType,
+        ename: str | None,
+        message: str,
+        context: EventContext | None,
+        data: dict,
+    ):
+        """Create and emit an event."""
+        evt = Event(
+            type=etype,
+            name=ename,
+            namespace=self.namespace,
+            message=message,
+            context=context,
+            data=data,
+        )
+        self._emit_event(evt)
+
+    def debug(
+        self,
+        message: str,
+        name: str | None = None,
+        context: EventContext = None,
+        **data,
+    ):
+        """Log a debug message."""
+        self.event("debug", name, message, context, data)
+
+    def info(
+        self,
+        message: str,
+        name: str | None = None,
+        context: EventContext = None,
+        **data,
+    ):
+        """Log an info message."""
+        self.event("info", name, message, context, data)
+
+    def warning(
+        self,
+        message: str,
+        name: str | None = None,
+        context: EventContext = None,
+        **data,
+    ):
+        """Log a warning message."""
+        self.event("warning", name, message, context, data)
+
+    def error(
+        self,
+        message: str,
+        name: str | None = None,
+        context: EventContext = None,
+        **data,
+    ):
+        """Log an error message."""
+        self.event("error", name, message, context, data)
+
+    def progress(
+        self,
+        message: str,
+        name: str | None = None,
+        percentage: float = None,
+        context: EventContext = None,
+        **data,
+    ):
+        """Log a progress message."""
+        merged_data = dict(percentage=percentage, **data)
+        self.event("progress", name, message, context, merged_data)
+
+
+@contextmanager
+def event_context(
+    logger: Logger,
+    message: str,
+    event_type: EventType = "info",
+    name: str | None = None,
+    **data,
+):
+    """
+    Times a synchronous block, logs an event after completion.
+    Because logger methods are async, we schedule the final log.
+    """
+    start_time = time.time()
+    try:
+        yield
+    finally:
+        duration = time.time() - start_time
+
+        logger.event(
+            event_type,
+            name,
+            f"{message} finished in {duration:.3f}s",
+            None,
+            {"duration": duration, **data},
+        )
+
+
+# TODO: saqadri - check if we need this
+@asynccontextmanager
+async def async_event_context(
+    logger: Logger,
+    message: str,
+    event_type: EventType = "info",
+    name: str | None = None,
+    **data,
+):
+    """
+    Times an asynchronous block, logs an event after completion.
+    Because logger methods are async, we schedule the final log.
+    """
+    start_time = time.time()
+    try:
+        yield
+    finally:
+        duration = time.time() - start_time
+        logger.event(
+            event_type,
+            name,
+            f"{message} finished in {duration:.3f}s",
+            None,
+            {"duration": duration, **data},
+        )
+
+
+class LoggingConfig:
+    """Global configuration for the logging system."""
+
+    _initialized = False
+
+    @classmethod
+    async def configure(
+        cls,
+        event_filter: EventFilter | None = None,
+        transport: EventTransport | None = None,
+        batch_size: int = 100,
+        flush_interval: float = 2.0,
+        **kwargs: Any,
+    ):
+        """
+        Configure the logging system.
+
+        Args:
+            event_filter: Default filter for all loggers
+            transport: Transport for sending events to external systems
+            batch_size: Default batch size for batching listener
+            flush_interval: Default flush interval for batching listener
+            **kwargs: Additional configuration options
+        """
+        if cls._initialized:
+            return
+
+        bus = AsyncEventBus.get(transport=transport)
+
+        # Add standard listeners
+        if "logging" not in bus.listeners:
+            bus.add_listener("logging", LoggingListener(event_filter=event_filter))
+
+        # Only add progress listener if enabled in settings
+        if "progress" not in bus.listeners and kwargs.get("progress_display", True):
+            bus.add_listener("progress", ProgressListener())
+
+        if "batching" not in bus.listeners:
+            bus.add_listener(
+                "batching",
+                BatchingListener(
+                    event_filter=event_filter,
+                    batch_size=batch_size,
+                    flush_interval=flush_interval,
+                ),
+            )
+
+        await bus.start()
+        cls._initialized = True
+
+    @classmethod
+    async def shutdown(cls):
+        """Shutdown the logging system gracefully."""
+        if not cls._initialized:
+            return
+        bus = AsyncEventBus.get()
+        await bus.stop()
+        cls._initialized = False
+
+    @classmethod
+    @asynccontextmanager
+    async def managed(cls, **config_kwargs):
+        """Context manager for the logging system lifecycle."""
+        try:
+            await cls.configure(**config_kwargs)
+            yield
+        finally:
+            await cls.shutdown()
+
+
+_logger_lock = threading.Lock()
+_loggers: Dict[str, Logger] = {}
+
+
+def get_logger(namespace: str) -> Logger:
+    """
+    Get a logger instance for a given namespace.
+    Creates a new logger if one doesn't exist for this namespace.
+
+    Args:
+        namespace: The namespace for the logger (e.g. "agent.helper", "workflow.demo")
+
+    Returns:
+        A Logger instance for the given namespace
+    """
+
+    with _logger_lock:
+        if namespace not in _loggers:
+            _loggers[namespace] = Logger(namespace)
+        return _loggers[namespace]
+
+
+##########
+# Example
+##########
+
+
+# class Agent:
+#     """Shows how to combine Logger with OTel's @telemetry.traced decorator."""
+
+#     def __init__(self, name: str):
+#         self.logger = Logger(f"agent.{name}")
+
+#     @telemetry.traced("agent.call_tool", kind=SpanKind.CLIENT)
+#     async def call_tool(self, tool_name: str, **kwargs):
+#         await self.logger.info(
+#             f"Calling tool '{tool_name}'", name="TOOL_CALL_START", **kwargs
+#         )
+#         await asyncio.sleep(random.uniform(0.1, 0.3))
+#         # Possibly do real logic here
+#         await self.logger.debug(
+#             f"Completed tool call '{tool_name}'", name="TOOL_CALL_END"
+#         )
+
+
+# class Workflow:
+#     """Example workflow that logs multiple steps, also with optional tracing."""
+
+#     def __init__(self, name: str, steps: List[str]):
+#         self.logger = Logger(f"workflow.{name}")
+#         self.steps = steps
+
+#     @telemetry.traced("workflow.run", kind=SpanKind.INTERNAL)
+#     async def run(self):
+#         await self.logger.info(
+#             "Workflow started", name="WORKFLOW_START", steps=len(self.steps)
+#         )
+#         for i, step_name in enumerate(self.steps, start=1):
+#             pct = round((i / len(self.steps)) * 100, 2)
+#             await self.logger.progress(
+#                 f"Executing {step_name}", name="WORKFLOW_STEP", percentage=pct
+#             )
+#             await asyncio.sleep(random.uniform(0.1, 0.3))
+#             await self.logger.milestone(
+#                 f"Completed {step_name}", name="WORKFLOW_MILESTONE", step_index=i
+#             )
+#         await self.logger.status("Workflow complete", name="WORKFLOW_DONE")
+
+
+# ###############################################################################
+# # 10) Demo Main
+# ###############################################################################
+
+
+# async def main():
+#     # 1) Configure Python logging
+#     logging.basicConfig(level=logging.INFO)
+
+#     # 2) Get the event bus and add local listeners
+#     bus = AsyncEventBus.get()
+#     bus.add_listener("logging", LoggingListener())
+#     bus.add_listener("batching", BatchingListener(batch_size=3, flush_interval=2.0))
+
+#     # 3) Optionally set up distributed transport
+#     # configure_distributed("https://my-remote-logger.example.com")
+
+#     # 4) Start the event bus
+#     await bus.start()
+
+#     # 5) Run example tasks
+#     agent = Agent("assistant")
+#     workflow = Workflow("demo_flow", ["init", "process", "cleanup"])
+
+#     agent_task = asyncio.create_task(agent.call_tool("my-tool", foo="bar"))
+#     workflow_task = asyncio.create_task(workflow.run())
+
+#     # Also demonstrate timed context manager
+#     logger = Logger("misc")
+#     with event_context(
+#         logger, "SynchronousBlock", event_type="info", name="SYNCHRONOUS_BLOCK"
+#     ):
+#         time.sleep(0.5)  # do a blocking operation
+
+#     # Wait for tasks
+#     await asyncio.gather(agent_task, workflow_task)
+
+#     # 6) Stop the bus (flush & close)
+#     await bus.stop()
+
+
+# if __name__ == "__main__":
+#     asyncio.run(main())

mcp_agent/logging/rich_progress.py

@@ -0,0 +1,120 @@
+"""Rich-based progress display for MCP Agent."""
+
+import time
+from typing import Optional
+from rich.console import Console
+from mcp_agent.console import console as default_console
+from mcp_agent.event_progress import ProgressEvent, ProgressAction
+from rich.progress import Progress, SpinnerColumn, TextColumn
+from contextlib import contextmanager
+
+
+class RichProgressDisplay:
+    """Rich-based display for progress events."""
+
+    def __init__(self, console: Optional[Console] = None):
+        """Initialize the progress display."""
+        self.console = console or default_console
+        self._taskmap = {}
+        self._progress = Progress(
+            SpinnerColumn(spinner_name="simpleDotsScrolling"),
+            TextColumn(
+                "[progress.description]{task.description}|",
+                #                table_column=Column(max_width=16),
+            ),
+            TextColumn(text_format="{task.fields[target]:<16}", style="Bold Blue"),
+            TextColumn(text_format="{task.fields[details]}", style="dim white"),
+            console=self.console,
+            transient=False,
+        )
+        self._paused = False
+
+    def start(self):
+        """start"""
+
+        self._progress.start()
+
+    def stop(self):
+        """stop"""
+        self._progress.stop()
+
+    def pause(self):
+        """Pause the progress display."""
+        if not self._paused:
+            self._paused = True
+
+            for task in self._progress.tasks:
+                task.visible = False
+            self._progress.stop()
+
+    def resume(self):
+        """Resume the progress display."""
+        if self._paused:
+            for task in self._progress.tasks:
+                task.visible = True
+            self._paused = False
+            self._progress.start()
+
+    @contextmanager
+    def paused(self):
+        """Context manager for temporarily pausing the display."""
+        self.pause()
+        try:
+            yield
+        finally:
+            self.resume()
+
+    def _get_action_style(self, action: ProgressAction) -> str:
+        """Map actions to appropriate styles."""
+        return {
+            ProgressAction.STARTING: "bold yellow",
+            ProgressAction.INITIALIZED: "dim green",
+            ProgressAction.CHATTING: "bold blue",
+            ProgressAction.READY: "dim green",
+            ProgressAction.ROUTING: "bold blue",
+            ProgressAction.CALLING_TOOL: "bold magenta",
+            ProgressAction.FINISHED: "black on green",
+            ProgressAction.SHUTDOWN: "black on red",
+            ProgressAction.AGGREGATOR_INITIALIZED: "bold green",
+        }.get(action, "white")
+
+    def update(self, event: ProgressEvent) -> None:
+        """Update the progress display with a new event."""
+        task_name = event.agent_name or "default"
+        # Create new task if needed
+        if task_name not in self._taskmap:
+            task_id = self._progress.add_task(
+                "",
+                total=None,
+                target=f"{event.target}",
+                details=f"{event.agent_name}",
+            )
+            self._taskmap[task_name] = task_id
+        else:
+            task_id = self._taskmap[task_name]
+
+        self._progress.update(
+            task_id,
+            description=f"[{self._get_action_style(event.action)}]{event.action.value:<15}",
+            target=event.target,
+            details=event.details if event.details else "",
+            task_name=task_name,
+        )
+
+        if (
+            event.action == ProgressAction.INITIALIZED
+            or event.action == ProgressAction.READY
+        ):
+            self._progress.update(task_id, completed=100, total=100)
+        elif event.action == ProgressAction.FINISHED:
+            self._progress.update(
+                task_id,
+                completed=100,
+                total=100,
+                details=f" / Elapsed Time {time.strftime('%H:%M:%S', time.gmtime(self._progress.tasks[task_id].elapsed))}",
+            )
+            for task in self._progress.tasks:
+                if task.id != task_id:
+                    task.visible = False
+        else:
+            self._progress.reset(task_id)

mcp_agent/logging/tracing.py

@@ -0,0 +1,140 @@
+"""
+Telemetry manager that defines distributed tracing decorators for OpenTelemetry traces/spans
+for the Logger module for MCP Agent
+"""
+
+import asyncio
+import functools
+from typing import Any, Dict, Callable, Optional, Tuple, TYPE_CHECKING
+
+from opentelemetry import trace
+from opentelemetry.context import Context as OtelContext
+from opentelemetry.propagate import extract as otel_extract
+from opentelemetry.trace import set_span_in_context
+from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+
+from opentelemetry.trace import SpanKind, Status, StatusCode
+
+from mcp_agent.context_dependent import ContextDependent
+
+if TYPE_CHECKING:
+    from mcp_agent.context import Context
+
+
+class TelemetryManager(ContextDependent):
+    """
+    Simple manager for creating OpenTelemetry spans automatically.
+    Decorator usage: @telemetry.traced("SomeSpanName")
+    """
+
+    def __init__(self, context: Optional["Context"] = None, **kwargs):
+        # If needed, configure resources, exporters, etc.
+        # E.g.: from opentelemetry.sdk.trace import TracerProvider
+        # trace.set_tracer_provider(TracerProvider(...))
+        super().__init__(context=context, **kwargs)
+
+    def traced(
+        self,
+        name: str | None = None,
+        kind: SpanKind = SpanKind.INTERNAL,
+        attributes: Dict[str, Any] = None,
+    ) -> Callable:
+        """
+        Decorator that automatically creates and manages a span for a function.
+        Works for both async and sync functions.
+        """
+
+        def decorator(func):
+            span_name = name or f"{func.__module__}.{func.__qualname__}"
+
+            tracer = self.context.tracer or trace.get_tracer("mcp_agent")
+
+            @functools.wraps(func)
+            async def async_wrapper(*args, **kwargs):
+                with tracer.start_as_current_span(span_name, kind=kind) as span:
+                    if attributes:
+                        for k, v in attributes.items():
+                            span.set_attribute(k, v)
+                    # Record simple args
+                    self._record_args(span, args, kwargs)
+                    try:
+                        res = await func(*args, **kwargs)
+                        return res
+                    except Exception as e:
+                        span.record_exception(e)
+                        span.set_status(Status(StatusCode.ERROR))
+                        raise
+
+            @functools.wraps(func)
+            def sync_wrapper(*args, **kwargs):
+                with tracer.start_as_current_span(span_name, kind=kind) as span:
+                    if attributes:
+                        for k, v in attributes.items():
+                            span.set_attribute(k, v)
+                    # Record simple args
+                    self._record_args(span, args, kwargs)
+                    try:
+                        res = func(*args, **kwargs)
+                        return res
+                    except Exception as e:
+                        span.record_exception(e)
+                        span.set_status(Status(StatusCode.ERROR))
+                        raise
+
+            if asyncio.iscoroutinefunction(func):
+                return async_wrapper
+            else:
+                return sync_wrapper
+
+        return decorator
+
+    def _record_args(self, span, args, kwargs):
+        """Optionally record primitive args as span attributes."""
+        for i, arg in enumerate(args):
+            if isinstance(arg, (str, int, float, bool)):
+                span.set_attribute(f"arg_{i}", str(arg))
+        for k, v in kwargs.items():
+            if isinstance(v, (str, int, float, bool)):
+                span.set_attribute(k, str(v))
+
+
+class MCPRequestTrace:
+    """Helper class for trace context propagation in MCP"""
+
+    @staticmethod
+    def start_span_from_mcp_request(
+        method: str, params: Dict[str, Any]
+    ) -> Tuple[trace.Span, OtelContext]:
+        """Extract trace context from incoming MCP request and start a new span"""
+        # Extract trace context from _meta if present
+        carrier = {}
+        _meta = params.get("_meta", {})
+        if "traceparent" in _meta:
+            carrier["traceparent"] = _meta["traceparent"]
+        if "tracestate" in _meta:
+            carrier["tracestate"] = _meta["tracestate"]
+
+        # Extract context and start span
+        ctx = otel_extract(carrier, context=OtelContext())
+        tracer = trace.get_tracer(__name__)
+        span = tracer.start_span(method, context=ctx, kind=SpanKind.SERVER)
+        return span, set_span_in_context(span)
+
+    @staticmethod
+    def inject_trace_context(arguments: Dict[str, Any]) -> Dict[str, Any]:
+        """Inject current trace context into outgoing MCP request arguments"""
+        carrier = {}
+        TraceContextTextMapPropagator().inject(carrier)
+
+        # Create or update _meta with trace context
+        _meta = arguments.get("_meta", {})
+        if "traceparent" in carrier:
+            _meta["traceparent"] = carrier["traceparent"]
+        if "tracestate" in carrier:
+            _meta["tracestate"] = carrier["tracestate"]
+        arguments["_meta"] = _meta
+
+        return arguments
+
+
+telemetry = TelemetryManager()