mermaid-trace 0.4.0__py3-none-any.whl → 0.5.3.post0__py3-none-any.whl

mermaid_trace/integrations/fastapi.py

@@ -1,25 +1,43 @@
+"""
+FastAPI Integration Module for MermaidTrace.
+
+This module provides the middleware necessary to integrate MermaidTrace with
+FastAPI applications. It serves as the bridge between HTTP requests and the
+sequence diagram generation logic.
+
+Key functionalities include:
+- Middleware for intercepting all incoming HTTP requests.
+- Automatic extraction of tracing headers (X-Source, X-Trace-ID).
+- Initialization of logging context for request lifecycles.
+- Automatic logging of request start and response completion (success or error).
+"""
+
 from typing import Any, TYPE_CHECKING
 import time
 import uuid
+import traceback
 
 from ..core.events import FlowEvent
 from ..core.context import LogContext
 from ..core.decorators import get_flow_logger
 
+# Conditional imports to support optional FastAPI dependency
 if TYPE_CHECKING:
+    # For static type checkers (mypy, pyright), import the actual types.
     from fastapi import Request, Response
     from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
 else:
     try:
+        # Runtime import attempt for FastAPI and Starlette.
         from fastapi import Request, Response
         from starlette.middleware.base import (
             BaseHTTPMiddleware,
             RequestResponseEndpoint,
         )
     except ImportError:
-        # Handle the case where FastAPI/Starlette are not installed.
-        # We define dummy types to prevent NameErrors at import time,
-        # but instantiation will fail explicitly in __init__.
+        # Fallback for when FastAPI is not installed in the environment.
+        # This prevents ImportErrors when importing this module without FastAPI.
+        # However, instantiating the middleware will still fail.
         BaseHTTPMiddleware = object  # type: ignore[misc,assignment]
         Request = Any  # type: ignore[assignment]
         Response = Any  # type: ignore[assignment]
@@ -30,11 +48,22 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
     """
     FastAPI Middleware to trace HTTP requests as interactions in the sequence diagram.
 
-    This middleware acts as the entry point for tracing a web request. It:
-    1. Identifies the client (Source).
-    2. Logs the incoming request.
-    3. Initializes the `LogContext` for the request lifecycle.
-    4. Logs the response or error.
+    This middleware wraps the entire request processing pipeline. It is responsible for
+    recording the initial interaction between an external client (Source) and this
+    service (Target).
+
+    Middleware Logic:
+    1.  **Request Interception**: Captures the request before it reaches any route handler.
+    2.  **Context Initialization**: Sets up the `LogContext` with the current service name
+        and trace ID, ensuring all internal function calls are correctly associated.
+    3.  **Event Logging**: Logs the "Request" event (Client -> API) and the corresponding
+        "Response" event (API -> Client).
+    4.  **Error Handling**: Captures exceptions, logs error events (API --x Client),
+        and re-raises them to standard error handlers.
+
+    Attributes:
+        app_name (str): The name of the current service/application. This name will
+                        appear as a participant in the generated Mermaid sequence diagram.
     """
 
     def __init__(self, app: Any, app_name: str = "FastAPI"):
@@ -42,13 +71,20 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
         Initialize the middleware.
 
         Args:
-            app: The FastAPI application instance.
-            app_name: The name of this service to appear in the diagram (e.g., "UserAPI").
+            app (Any): The FastAPI application instance.
+            app_name (str): The name of this service to appear in the diagram (e.g., "UserAPI").
+                            Defaults to "FastAPI".
+
+        Raises:
+            ImportError: If FastAPI or Starlette is not installed in the current environment.
         """
+        # Validate that the necessary dependencies are present.
         if BaseHTTPMiddleware is object:  # type: ignore[comparison-overlap]
             raise ImportError(
                 "FastAPI/Starlette is required to use MermaidTraceMiddleware"
             )
+
+        # Initialize the base class.
         super().__init__(app)
         self.app_name = app_name
 
@@ -56,59 +92,88 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
         self, request: Request, call_next: RequestResponseEndpoint
     ) -> Response:
         """
-        Intercepts the incoming request.
+        Dispatch method to handle the incoming request.
+
+        This is the core logic of the middleware. It wraps the `call_next` execution
+        with tracing logic.
+
+        Request Tracing & Header Handling:
+        - **X-Source**: Used to identify the caller. If present, the diagram will show
+          an arrow from `X-Source` to `app_name`. If missing, defaults to "Client".
+        - **X-Trace-ID**: Used for distributed tracing. If provided, it links this
+          request to an existing trace. If missing, a new UUID is generated.
 
         Args:
-            request (Request): The incoming HTTP request.
-            call_next (Callable): The function to call the next middleware or endpoint.
+            request (Request): The incoming HTTP request object.
+            call_next (RequestResponseEndpoint): A callable that invokes the next
+                                                 middleware or the route handler.
 
         Returns:
-            Response: The HTTP response.
+            Response: The HTTP response generated by the application.
         """
-        # 1. Determine Source (Client)
-        # Try to get a specific ID from headers (useful for distributed tracing),
-        # otherwise fallback to "Client".
+        # ----------------------------------------------------------------------
+        # 1. Header Handling and Metadata Extraction
+        # ----------------------------------------------------------------------
+
+        # Determine the source participant (Who is calling us?).
+        # If the request comes from another service traced by MermaidTrace,
+        # it might include the 'X-Source' header.
         source = request.headers.get("X-Source", "Client")
 
-        # Determine Trace ID
-        # Check X-Trace-ID header or generate new UUID
+        # Determine the unique Trace ID.
+        # This ID is critical for grouping all logs related to a single request flow.
         trace_id = request.headers.get("X-Trace-ID") or str(uuid.uuid4())
 
-        # 2. Determine Action
-        # Format: "METHOD /path" (e.g., "GET /users")
+        # Define the action name for the diagram arrow.
+        # Format: "METHOD /path" (e.g., "GET /api/v1/users")
         action = f"{request.method} {request.url.path}"
 
+        # Get the configured logger for flow events.
         logger = get_flow_logger()
 
-        # 3. Log Request (Source -> App)
+        # ----------------------------------------------------------------------
+        # 2. Log Request Start (Source -> App)
+        # ----------------------------------------------------------------------
+
+        # Create the 'Request' event representing the call coming into this service.
         req_event = FlowEvent(
             source=source,
             target=self.app_name,
             action=action,
             message=action,
+            # Include query parameters in the note if they exist.
             params=f"query={request.query_params}" if request.query_params else None,
             trace_id=trace_id,
         )
+
+        # Log the event. This writes the JSON entry that the visualizer will parse.
         logger.info(
             f"{source}->{self.app_name}: {action}", extra={"flow_event": req_event}
         )
 
-        # 4. Set Context and Process Request
-        # We set the current participant to the app name.
-        # `ascope` ensures this context applies to all code running within `call_next`.
-        # This includes route handlers, dependencies, and other middlewares called after this one.
+        # ----------------------------------------------------------------------
+        # 3. Context Setup and Request Processing
+        # ----------------------------------------------------------------------
+
+        # Initialize the LogContext for this async task.
+        # Any 'traced' function called within this block will inherit 'trace_id'
+        # and see 'participant' as self.app_name.
         async with LogContext.ascope(
             {"participant": self.app_name, "trace_id": trace_id}
         ):
             start_time = time.time()
             try:
-                # Pass control to the application
-                # This executes the actual route logic
+                # Process the request by calling the next item in the middleware chain.
                 response = await call_next(request)
 
-                # 5. Log Response (App -> Source)
-                # Calculate execution duration for the response label
+                # ------------------------------------------------------------------
+                # 4. Log Success Response (App -> Source)
+                # ------------------------------------------------------------------
+
+                # Calculate execution time for performance insights.
                 duration = (time.time() - start_time) * 1000
+
+                # Create the 'Return' event (dashed line back to caller).
                 resp_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -125,10 +190,17 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                 return response
 
             except Exception as e:
-                # 6. Log Error (App --x Source)
-                # This captures unhandled exceptions that bubble up to the middleware
-                # Note: FastAPI's ExceptionHandlers might catch this before it reaches here.
-                # If so, you might see a successful return with 500 status instead.
+                # ------------------------------------------------------------------
+                # 5. Log Error Response (App --x Source)
+                # ------------------------------------------------------------------
+
+                # Capture full stack trace for the error.
+                stack_trace = "".join(
+                    traceback.format_exception(type(e), e, e.__traceback__)
+                )
+
+                # If an unhandled exception occurs, log it as an error event.
+                # This will render as a cross (X) on the sequence diagram return arrow.
                 err_event = FlowEvent(
                     source=self.app_name,
                     target=source,
@@ -137,9 +209,13 @@ class MermaidTraceMiddleware(BaseHTTPMiddleware):
                     is_return=True,
                     is_error=True,
                     error_message=str(e),
+                    stack_trace=stack_trace,
                     trace_id=trace_id,
                 )
                 logger.error(
                     f"{self.app_name}-x{source}: Error", extra={"flow_event": err_event}
                 )
+
+                # Re-raise the exception so FastAPI's exception handlers can take over.
+                # We strictly monitor the flow here, not swallow errors.
                 raise

{mermaid_trace-0.4.0.dist-info → mermaid_trace-0.5.3.post0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mermaid-trace
-Version: 0.4.0
+Version: 0.5.3.post0
 Summary: Visualize your Python code execution flow as Mermaid Sequence Diagrams.
 Project-URL: Documentation, https://github.com/xt765/mermaid-trace#readme
 Project-URL: Changelog, https://github.com/xt765/mermaid-trace/blob/main/docs/en/CHANGELOG.md
@@ -39,7 +39,6 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
 Classifier: Topic :: Software Development :: Debuggers
@@ -63,24 +62,57 @@ Description-Content-Type: text/markdown
 
 # MermaidTrace: The Python Logger That Draws Diagrams
 
-[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
-[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square)](https://pypi.org/project/mermaid-trace/)
+🌐 **Language**: [English](README.md) | [中文](README_CN.md)
+
+[![PyPI version](https://img.shields.io/pypi/v/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/mermaid-trace.svg?style=flat-square&color=blue)](https://pypi.org/project/mermaid-trace/)
 [![License](https://img.shields.io/github/license/xt765/mermaid-trace?style=flat-square)](LICENSE)
 [![CI Status](https://img.shields.io/github/actions/workflow/status/xt765/mermaid-trace/ci.yml?style=flat-square&label=CI)](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
 [![Codecov](https://img.shields.io/codecov/c/github/xt765/mermaid-trace?style=flat-square&logo=codecov)](https://codecov.io/gh/xt765/mermaid-trace)
 
+---
+
+## 📋 Overview
+
 **Stop reading logs. Start watching them.**
 
 MermaidTrace is a specialized logging tool that automatically generates [Mermaid JS](https://mermaid.js.org/) sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.
 
-## ✨ Features
+---
+
+## 📚 Documentation
+
+### Core Documentation
+
+[User Guide](docs/en/USER_GUIDE.md) · [API Reference](docs/en/API.md) · [Contributing Guidelines](docs/en/CONTRIBUTING.md) · [Changelog](docs/en/CHANGELOG.md) · [License](docs/en/LICENSE)
+
+### Code Comment Documents (Chinese)
+
+| Category | Links |
+| :--- | :--- |
+| **Core Modules** | [Context](docs/zh/code_comments/src/mermaid_trace/core/context.md) · [Decorators](docs/zh/code_comments/src/mermaid_trace/core/decorators.md) · [Events](docs/zh/code_comments/src/mermaid_trace/core/events.md) · [Formatter](docs/zh/code_comments/src/mermaid_trace/core/formatter.md) |
+| **Handlers** | [Async Handler](docs/zh/code_comments/src/mermaid_trace/handlers/async_handler.md) · [Mermaid Handler](docs/zh/code_comments/src/mermaid_trace/handlers/mermaid_handler.md) |
+| **Integrations** | [FastAPI](docs/zh/code_comments/src/mermaid_trace/integrations/fastapi.md) |
+| **Others** | [init](docs/zh/code_comments/src/mermaid_trace/__init__.md) · [CLI](docs/zh/code_comments/src/mermaid_trace/cli.md) |
+
+---
+
+## ✨ Key Features
 
 - **Decorator-Driven**: Just add `@trace` or `@trace_interaction` to your functions.
+- **Auto-Instrumentation**: Use `@trace_class` to trace a whole class at once.
+- **Third-Party Patching**: Use `patch_object` to trace calls inside external libraries.
 - **Auto-Diagramming**: Generates `.mmd` files that can be viewed in VS Code, GitHub, or Mermaid Live Editor.
 - **Async Support**: Works seamlessly with `asyncio` coroutines.
 - **Context Inference**: Automatically tracks nested calls and infers `source` participants using `contextvars`.
-- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing.
-- **CLI Tool**: Built-in viewer to preview diagrams in your browser.
+- **Intelligent Collapsing**: Prevents diagram explosion by collapsing repetitive high-frequency calls and identifying recurring patterns (e.g., loops).
+- **Detailed Exceptions**: Captures full stack traces for errors, displayed in interactive notes.
+- **Simplified Objects**: Automatically cleans up memory addresses (e.g., `<__main__.Obj at 0x...>` -> `<Obj>`) and **groups consecutive identical items** in lists/tuples (e.g., `[<Obj> x 5]`) for cleaner diagrams.
+- **Log Rotation**: Supports `RotatingMermaidFileHandler` for handling long-running systems by splitting logs based on size or time.
+- **FastAPI Integration**: Includes middleware for zero-config HTTP request tracing, supporting distributed tracing via `X-Trace-ID` and `X-Source` headers.
+- **CLI Tool**: Built-in viewer with live-reload to preview diagrams in your browser.
+
+---
 
 ## 🚀 Quick Start
 
@@ -97,7 +129,8 @@ from mermaid_trace import trace, configure_flow
 import time
 
 # 1. Configure output
-configure_flow("my_flow.mmd")
+# Recommendation: Store diagrams in a dedicated directory (e.g., mermaid_diagrams/)
+configure_flow("mermaid_diagrams/my_flow.mmd", async_mode=True)
 
 # 2. Add decorators
 @trace(source="Client", target="PaymentService", action="Process Payment")
@@ -114,6 +147,29 @@ def check_balance(amount):
 process_payment(100)
 ```
 
+### Configuration
+
+You can configure global settings via `configure_flow` or environment variables to control performance and behavior.
+
+```python
+configure_flow(
+    "flow.mmd", 
+    overwrite=True,    # Overwrite the file on each restart (default: True)
+    level=logging.DEBUG, 
+    queue_size=5000,  # Increase buffer for high-throughput
+    config_overrides={
+        "capture_args": False,       # Disable arg capturing for max performance
+        "max_string_length": 100     # Increase string truncation limit
+    }
+)
+```
+
+**Environment Variables:**
+- `MERMAID_TRACE_CAPTURE_ARGS` (true/false)
+- `MERMAID_TRACE_MAX_STRING_LENGTH` (int)
+- `MERMAID_TRACE_MAX_ARG_DEPTH` (int)
+- `MERMAID_TRACE_QUEUE_SIZE` (int)
+
 ### Nested Calls (Context Inference)
 
 You don't need to specify `source` every time. MermaidTrace infers it from the current context.
@@ -151,15 +207,26 @@ Visualize your generated `.mmd` files instantly:
 mermaid-trace serve my_flow.mmd
 ```
 
-## 📂 Documentation
+### Examples
 
-- [English Documentation](docs/en/USER_GUIDE.md)
-- [中文文档](README_CN.md)
+Check out the [examples/](examples/) directory for a complete set of demos covering all features:
+- **[Basic Usage](examples/01_basic_usage.py)**: Decorators and class methods.
+- **[Advanced Instrumentation](examples/02_advanced_instrumentation.py)**: `@trace_class` and `patch_object` for third-party libraries.
+- **[Async & Concurrency](examples/03_async_concurrency.py)**: Tracing `asyncio` and concurrent tasks.
+- **[Error Handling](examples/04_error_handling.py)**: Stack trace capture and error rendering.
+- **[Intelligent Collapsing](examples/05_intelligent_collapsing.py)**: Keeping diagrams clean in loops.
+- **[FastAPI Integration](examples/06_fastapi_integration.py)**: Middleware for web apps.
+- **[Full Stack App](examples/07_full_stack_app.py)**: Comprehensive example with FastAPI, SQLAlchemy, and Pydantic.
+- **[Log Rotation](examples/08-log-rotation.py)**: Handling long-running processes with file rotation.
+
+---
 
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
 
+---
+
 ## 📄 License
 
 MIT

mermaid_trace-0.5.3.post0.dist-info/RECORD

@@ -0,0 +1,19 @@
+mermaid_trace/__init__.py,sha256=EnAsz6R6ag4dtabdHEg1wdB2k7V1uwmwpYTTC41GQX4,6721
+mermaid_trace/cli.py,sha256=g7Qriiox9YqfJutUntE1a7GwByg62wGwQcLfpvicjT8,15076
+mermaid_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mermaid_trace/core/config.py,sha256=akTOc3m_bzcZ7e1Qtf1n5Ct9Dj8XPTTcWzATG3-qJHw,1890
+mermaid_trace/core/context.py,sha256=wr-Ys3c6PsYCtbPUsQTrnaciSkP-fofxOewo4oZ27QM,8556
+mermaid_trace/core/decorators.py,sha256=2h7UzjQcL46jrCIdVMWSZT_4JlTsDkpY9M9Ihr0vuq4,23037
+mermaid_trace/core/events.py,sha256=2etS45A40GaP4dF_F6Jh99rhF2YVip4AjoZlLPuP6pQ,1949
+mermaid_trace/core/formatter.py,sha256=3KEq236E3GAj_j53MuBM2ndWm7Kx4KeywJWmoY5o568,11038
+mermaid_trace/core/utils.py,sha256=FagsMYLZcbmOgKmRo3v9tcRNVIpuc1YEKTAjcRk7keY,3410
+mermaid_trace/handlers/async_handler.py,sha256=WmLcULXHasapt7-W0p_Eltjmwvlq6r6BS6pViuseZ4w,8252
+mermaid_trace/handlers/mermaid_handler.py,sha256=Czar6JYSPTu5L1fQC0I8v1UpToD6aE_r96IkPpRSByw,6142
+mermaid_trace/integrations/__init__.py,sha256=uU_8E1tlP327Fn79kvzlgEdoiIpQLsWJl3BgyqgsFMQ,104
+mermaid_trace/integrations/fastapi.py,sha256=6LRs4Z508l38ymfj5SP39vOV6OLfYLRkpxyL_SxvudM,9483
+mermaid_trace-0.5.3.post0.dist-info/METADATA,sha256=FR1kgM-wlTzrFasLpIeqbWbV_X3h3TwwUkxQCvgbvo0,9959
+mermaid_trace-0.5.3.post0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+mermaid_trace-0.5.3.post0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
+mermaid_trace-0.5.3.post0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
+mermaid_trace-0.5.3.post0.dist-info/RECORD,,

mermaid_trace-0.4.0.dist-info/RECORD

@@ -1,16 +0,0 @@
-mermaid_trace/__init__.py,sha256=yhc-shETKioVEQEfqmCGFyVelRR3_ypeClbMR_D2oBQ,5267
-mermaid_trace/cli.py,sha256=F5-QfnKp_Et719IKWvU5IAWZTpq9ft01ow62DqNpHdA,9477
-mermaid_trace/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mermaid_trace/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mermaid_trace/core/context.py,sha256=WyTKbC_I1ge802VUj9PdUiqa-VgL1r3DQUW_y8PlG8M,6618
-mermaid_trace/core/decorators.py,sha256=13-n6qsmWnInpKgQ0Bgnnn5aQIWkRZ7raTD2xVtKVmU,12303
-mermaid_trace/core/events.py,sha256=TVtarp7IwfTR_C404ZWoyqBZmTtScROz5hWL0uel3G4,2857
-mermaid_trace/core/formatter.py,sha256=6k79eBU09TSCEUcDJN1mfn-_KMld0xXfKtQTKZb8Ogw,3178
-mermaid_trace/handlers/async_handler.py,sha256=uGC27TCgfxyvQQEiJ_7Ir1EFJdsLHBUzHEsLktEaFtM,1893
-mermaid_trace/handlers/mermaid_handler.py,sha256=JUq5gSQepNISreUYkyucS_rk27zGIiwSYFw_Lb8lL28,4314
-mermaid_trace/integrations/fastapi.py,sha256=GJL2H0Ypi4HqiAR-kkV4kSUTitdOj4RkhPi26GGNORM,5515
-mermaid_trace-0.4.0.dist-info/METADATA,sha256=4oszQifzCHhgCEI0Ly1nKAUuvcF-Bs-ejCReGUOsTbo,6287
-mermaid_trace-0.4.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-mermaid_trace-0.4.0.dist-info/entry_points.txt,sha256=WS57KT_870v0A4B87QDjQUqJcddMQxbCQyYeczDAX34,57
-mermaid_trace-0.4.0.dist-info/licenses/LICENSE,sha256=BrBog1Etiq9PdWy0SVQNVByIMD9ss4Edz-R0oXt49zA,1062
-mermaid_trace-0.4.0.dist-info/RECORD,,