MermaidTrace: The Python Logger That Draws Diagrams

🌐 Language: English | 中文

---

📋 Overview

Stop reading logs. Start watching them.

MermaidTrace is a specialized logging tool that automatically generates Mermaid JS sequence diagrams from your code execution. It's perfect for visualizing complex business logic, microservice interactions, or asynchronous flows.

---

📚 Documentation

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

---

✨ Key Features

• Decorator-Driven: Just add @trace or @trace_interaction to your functions.
• 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.

---

🚀 Quick Start

Installation

pip install mermaid-trace

Basic Usage

from mermaid_trace import trace, configure_flow
import time

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

# 2. Add decorators
@trace(source="Client", target="PaymentService", action="Process Payment")
def process_payment(amount):
    if check_balance(amount):
        return "Success"
    return "Failed"

@trace(source="PaymentService", target="Database", action="Check Balance")
def check_balance(amount):
    return True

# 3. Run your code
process_payment(100)

Nested Calls (Context Inference)

You don't need to specify source every time. MermaidTrace infers it from the current context.

@trace(source="Client", target="API")
def main():
    # Inside here, current participant is "API"
    service_call()

@trace(target="Service") # source inferred as "API"
def service_call():
    pass

FastAPI Integration

from fastapi import FastAPI
from mermaid_trace.integrations.fastapi import MermaidTraceMiddleware

app = FastAPI()
app.add_middleware(MermaidTraceMiddleware, app_name="MyAPI")

@app.get("/")
async def root():
    return {"message": "Hello World"}

CLI Viewer

Visualize your generated .mmd files instantly:

mermaid-trace serve my_flow.mmd

---

🤝 Contributing

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

---

📄 License

MIT