MermaidTrace: Visualize Your Python Code Logic

Stop drowning in cryptic logs. One line of code to transform complex execution logic into clear Mermaid sequence diagrams.

🌐 Language: English | 中文

---

⚡️ Understand MermaidTrace in 5 Seconds

1. Original Code (15+ lines)

@trace(source="User", target="OrderSys")
def create_order(user_id, items):
    # Complex business logic
    if not check_inventory(items):
        return "Out of Stock"

    # Nested logic calls
    price = calculate_price(items)
    discount = get_discount(user_id)
    final = price - discount

    # External service interactions
    res = pay_service.process(final)
    if res.success:
        update_stock(items)
        send_notif(user_id)
        return "Success"
    return "Failed"

2. Auto-Generated Sequence Diagram

sequenceDiagram
    autonumber
    User->>OrderSys: create_order(user_id, items)
    activate OrderSys
    OrderSys->>Inventory: check_inventory(items)
    Inventory-->>OrderSys: True
    OrderSys->>Pricing: calculate_price(items)
    Pricing-->>OrderSys: 100.0
    OrderSys->>UserDB: get_discount(user_id)
    UserDB-->>OrderSys: 5.0
    OrderSys->>PayService: process(95.0)
    activate PayService
    PayService-->>OrderSys: success
    deactivate PayService
    OrderSys->>Inventory: update_stock(items)
    OrderSys->>Notification: send_notif(user_id)
    OrderSys-->>User: "Success"
    deactivate OrderSys

Loading

---

🚀 Dynamic Demo & Online Tryout

🎬 Quick Demo

(Master Preview: Multi-file browsing, live-reload, and interactive pan/zoom)

sequenceDiagram
    participant CLI as mermaid-trace CLI
    participant App as Python App
    participant Web as Live Preview

    Note over CLI, Web: Enable Live Preview Mode
    CLI->>Web: Start HTTP Server (localhost:8000)
    App->>App: Run Logic (with @trace decorator)
    App->>App: Auto-update flow.mmd
    Web->>Web: File Change Detected (Hot Reload)
    Web-->>CLI: Render Latest Diagram

Loading

(From adding decorators to browser live preview in 10 seconds)

🛠️ Try Online (Google Colab)

No local setup required. Experience core features in your browser:

---

🎯 Why MermaidTrace? (Use Cases)

1. Master "Legacy" Codebases

Pain: Taking over a complex, undocumented legacy project with tangled function calls. Solution: Add @trace_class or @trace to entry points and run the code once. Value: Instantly generate a complete execution path map to understand the architecture.

2. Automated Technical Docs

Pain: Manual sequence diagrams are time-consuming and quickly become outdated. Solution: Integrate MermaidTrace during development. Value: Diagrams stay 100% in sync with your code logic automatically.

3. Debug Complex Recursion & Concurrency

Pain: Nested calls or async tasks produce interleaved logs that are impossible to read. Solution: Use built-in async support and intelligent collapsing. Value: Visualize recursion depth and concurrency flow to pinpoint logic bottlenecks.

---

🚀 Quick Start in 3 Steps

1. Install

pip install mermaid-trace

2. Add Decorators

from mermaid_trace import trace, configure_flow

# Configure output file
configure_flow("my_flow.mmd")

@trace(source="User", target="AuthService")
def login(username):
    return verify_db(username)

@trace(source="AuthService", target="DB")
def verify_db(username):
    return True

login("admin")

3. View Diagram

Run the built-in CLI tool to preview in real-time (with hot-reload):

# Basic preview
mermaid-trace serve my_flow.mmd

# Master mode (Directory browsing, zoom, multi-file switching)
mermaid-trace serve . --master
# Or preview a specific file in Master mode
mermaid-trace serve .\mermaid_diagrams\examples\08-log-rotation.mmd --master

🔗 LangChain Integration

Visualize LLM chains, agents, and RAG retrieval with a single handler:

from mermaid_trace.integrations.langchain import MermaidTraceCallbackHandler

handler = MermaidTraceCallbackHandler(host_name="MyAIApp")
# Pass to any LangChain object
chain.invoke({"input": "..."}, config={"callbacks": [handler]})

---

✨ Key Features

• Decorator-Driven: Simply add @trace or @trace_interaction to 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.
• Async Support: Seamlessly works with asyncio coroutines and concurrency.
• Enhanced Web UI: Interactive preview server with file browsing, auto-reload, and pan/zoom support (use --master).
• Intelligent Collapsing: Automatically collapses repetitive calls and identifies loops.
• FastAPI Integration: Middleware for zero-config HTTP request tracing.
• LangChain Integration: Callback Handler for LLM chains and agent visualization.
• Detailed Exceptions: Captures full stack traces for errors, displayed in the diagram.

---

📚 Documentation

Core Documentation

User Guide · API Reference · Contributing Guidelines · Changelog · License

Code Comment Documents

Category	Links
Core Modules	Context · Decorators · Events · Formatter
Handlers	Async Handler · Mermaid Handler
Integrations	FastAPI
Others	init · CLI

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

---

📄 License

MIT