MermaidTrace

Core Positioning#

MermaidTrace is an execution flow visualization tool designed for Python. It captures function calls at runtime via decorators (@trace, @trace_class, @trace_interaction) and automatically converts them to standard Mermaid JS sequence diagrams, addressing the limitations of traditional text logs in understanding complex logic.

Key Features#

Tracing Capabilities#

• Decorator-driven: @trace, @trace_interaction, @trace_class (covers all class public methods)
• Auto Sequence Diagram Generation: Function calls automatically converted to Mermaid syntax
• Native Async Support: Seamless support for asyncio coroutines and concurrent scenarios
• Smart Folding: Auto-detect and fold repeated calls (e.g., func (x10)), preventing diagram explosion
• Third-party Library Patching: patch_object traces external library methods without modifying source code

Privacy & Security#

• Built-in DataMasker for automatic data masking
• Configurable sensitive field masks (password, token, etc.)
• capture_args=False prevents sensitive parameters from being logged

Performance Control#

• Configurable sample_rate to control tracing percentage
• Async mode (async_mode=True) offloads log writing to background thread
• Queue size limit (queue_size=1000) prevents memory overflow in high-traffic scenarios

Distributed Tracing#

• W3C Trace Context standard support
• B3 and custom X-Trace-ID headers support
• FastAPI middleware for cross-service trace context propagation

Visualization & UI#

• FastAPI-powered interactive Web preview interface
• Real-time rendering (integrated mermaid.js)
• Pan and zoom support (svg-pan-zoom)
• Server-Sent Events (SSE) for auto-refresh
• Directory browsing and multi-file switching

Framework Integration#

FastAPI#

• Zero-config HTTP request tracing middleware
• Header propagation support

LangChain#

• MermaidTraceCallbackHandler supports Chains, LLMs, ChatModels, Tools, Retrievers
• Participant stack correctly tracks nested calls and return arrows
• RAG and Agent workflow visualization support

Log Management#

• RotatingMermaidFileHandler: Size-based rotation
• TimedRotatingMermaidFileHandler: Time-based rotation
• Auto-split .mmd files
• overwrite parameter clears diagram files on app restart

Error Handling#

• Captures complete Python traceback on exceptions
• Displays error details as Notes in Mermaid diagrams

Installation & Usage#

# Basic installation
pip install mermaid-trace

# FastAPI integration
pip install mermaid-trace[fastapi]

# LangChain integration
pip install mermaid-trace[langchain]

Quick Start#

from mermaid_trace import trace, configure_flow

configure_flow("my_flow.mmd")

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

login("admin")

CLI Preview#

mermaid-trace serve my_flow.mmd  # Preview single file
mermaid-trace serve .            # Preview directory

Use Cases#

1. Legacy Code Understanding: Quickly generate execution path diagrams for unknown codebases
2. Automated Documentation: Keep sequence diagrams 100% synchronized with code logic
3. Debugging Concurrency & Recursion: Visualize async task interleaving and recursion depth
4. Microservice Interaction Visualization: Trace call relationships between microservices
5. LLM Application Monitoring: Visualize LangChain Chains, Agent decisions, and RAG retrieval processes

Project Info#

• Python Version: >=3.10 (supports 3.10-3.14)
• Implementation: CPython, PyPy
• Latest Version: v0.7.0
• Test Coverage: >90%
• Type Annotations: 100% Mypy coverage