https://github.com/xt765/mermaid-trace
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.
https://github.com/xt765/mermaid-trace
fastapi graph graphics graphs langchain layered-architecture log logger logging mermaid mvc mvc-architecture pipy-package python python-script python3 src visual visualization
Last synced: about 1 month ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/xt765/mermaid-trace
- Owner: xt765
- License: mit
- Created: 2026-01-24T09:04:59.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-01-28T06:33:48.000Z (about 1 month ago)
- Last Synced: 2026-01-29T09:24:34.487Z (about 1 month ago)
- Topics: fastapi, graph, graphics, graphs, langchain, layered-architecture, log, logger, logging, mermaid, mvc, mvc-architecture, pipy-package, python, python-script, python3, src, visual, visualization
- Language: Python
- Homepage:
- Size: 433 KB
- Stars: 19
- Watchers: 0
- Forks: 4
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# MermaidTrace: The Python Logger That Draws Diagrams
π **Language**: [English](README.md) | [δΈζ](README_CN.md)
[](https://pypi.org/project/mermaid-trace/)
[](https://pypi.org/project/mermaid-trace/)
[](LICENSE)
[](https://github.com/xt765/mermaid-trace/actions/workflows/ci.yml)
[](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.
---
## π 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)
---
## β¨ 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
```bash
pip install mermaid-trace
```
### Basic Usage
```python
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.
```python
@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
```python
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:
```bash
mermaid-trace serve my_flow.mmd
```
---
## π€ Contributing
We welcome contributions! Please see [CONTRIBUTING.md](docs/en/CONTRIBUTING.md) for details.
---
## π License
MIT